Reference
Configuration
Every one of the 87 keys of webfluent.app.json, with its type and default, read from wf config schema --json.
webfluent.app.json
This chapter is the reference for webfluent.app.json, the file beside src/ that holds a project's settings. Look up a key here to find its type, its default and what it changes.
Every key is optional except name, so the smallest config is one line:
{ "name": "my-site" }
A key the build does not know draws the E112 warning, with the key it most likely meant — "defaultLocale" says to write default_locale — instead of being ignored (since 4.1).
Reading and changing the config
wf config lists every setting and edits the file without reformatting it (Command line):
wf config schemalists every setting with its type, the values it takes, its default and what it does.--jsonprints the same for a tool; an editor's settings window is built from it.wf config get PATHprints what the project sets at a dotted path, or the default.wf config set PATH VALUEchecks the value against the setting's type before it writes anything. It replaces a value in place, and adds a new key at the end of its section, in the section's own style.wf config unset PATHremoves a setting, so its default applies, and removes a section it leaves empty.
$ wf config set build.base_path /Docs
$ wf config set build.budget.app.js "40 kB"
$ wf config get dev.port
$ wf config unset build.base_path
Under a map such as build.budget, the rest of the path is one key, so build.budget.app.js names the app.js entry.
The defaults
This block is what a config holding only a name means. The compiler's test suite checks it against the compiler's own defaults. i18n, offline and apis are absent unless you add them.
{
"name": "my-site",
"version": "0.1.0",
"author": "",
"theme": {
"name": null,
"tokens": {},
"builtin": "full",
"dark": null
},
"build": {
"elements": [],
"output": "./build",
"minify": true,
"sourcemap": false,
"ssg": false,
"base_path": "",
"clean_urls": null,
"csp": false,
"split": true,
"compress": true,
"budget": {},
"runtime": "auto",
"media": {
"formats": ["webp"],
"widths": [480, 960, 1440, 1920],
"quality": 78,
"pipeline": true
},
"output_type": "spa",
"pdf": {
"page_size": "A4",
"margins": { "top": 72.0, "bottom": 72.0, "left": 72.0, "right": 72.0 },
"default_font": "Helvetica",
"default_font_size": 12.0,
"output_filename": null,
"fonts": [],
"system_fonts": true
},
"slides": {
"size": "16:9",
"width": null,
"height": null,
"default_font": "Helvetica",
"default_font_size": 24.0,
"margin": 60.0,
"show_slide_numbers": false,
"footer_text": null,
"background_color": null,
"chrome_color": null,
"output_filename": null,
"fonts": [],
"system_fonts": true
}
},
"dev": { "port": 3000, "hot_reload": true },
"meta": {
"integrity": {},
"title": "my-site",
"description": "",
"favicon": "",
"touch_icon": "",
"lang": "en",
"site_url": "",
"site_name": "",
"owner": "organization",
"same_as": [],
"job_title": "",
"image": "",
"image_alt": "",
"sitemap": true,
"fonts": [],
"preload": [],
"stylesheets": [],
"scripts": [],
"connect": [],
"img": [],
"frame": [],
"wasm": false,
"style_elements": false
},
"motion": { "duration": null, "easing": null },
"env": {},
"lints": {},
"public_env": []
}
wf init writes a shorter file than this one, and turns build.csp on.
The project
The top-level keys that describe the project itself.
| Key | Type | Default | Meaning |
|---|---|---|---|
|
|
string | — |
The only required key. The site's name, the PDF's file name when none is given, and the fallback for |
|
|
string |
|
The project's version, as you number it. Nothing in the build reads it. |
|
|
string |
|
Who wrote it. Nothing in the build reads it. |
build
How the project is compiled, and what the build writes.
| Key | Type | Default | Meaning |
|---|---|---|---|
|
|
string |
|
Where the build is written, relative to the project and inside it: a path that climbs out ( |
|
|
|
|
What the project builds: |
|
|
boolean |
|
Pre-renders every page to its own HTML file, so it is read before any script runs (Static sites and SPAs). |
|
|
string |
|
The sub-path the site is served under, such as |
|
|
|
unset |
How a route's address avoids a redirect on a host that adds a trailing slash. |
|
|
boolean |
|
Writes one script and stylesheet chunk per page, loaded when its route shows. Off, every page ships in |
|
|
boolean |
|
Strips comments and whitespace from the scripts and stylesheets. Off, the output is readable and larger. |
|
|
boolean |
|
Writes a source map (version 3) beside the bundle and each page's chunk — |
|
|
boolean |
|
Writes a gzipped |
|
|
|
|
|
|
|
boolean |
|
Emits a Content-Security-Policy and a |
|
|
map of file to size |
|
A gzipped size each named output should stay under: |
|
|
list of component names |
|
With |
|
|
object | below | The image pipeline. |
|
|
object | below | The paper outputs. |
build.media
The image pipeline: how the build resizes and re-encodes the pictures a program names (Add a picture).
| Key | Type | Default | Meaning |
|---|---|---|---|
|
|
list of |
|
The formats every |
|
|
list of integers |
|
The widths written, where smaller than the original. |
|
|
integer, 1–100 |
|
The encoding quality. WebP and JPEG are lossy at it. A file no smaller than the original is not written. |
|
|
boolean |
|
|
build.pdf
The page and type of a PDF build (PDF and slides).
| Key | Type | Default | Meaning |
|---|---|---|---|
|
|
string |
|
|
|
|
object of numbers |
|
|
|
|
string |
|
The document's family when its stylesheets name none: a standard name ( |
|
|
number |
|
In points; |
|
|
string | the project's name | The file written. |
|
|
list of paths |
|
Font files or directories, read as well as the project's |
|
|
boolean |
|
Whether this machine's fonts may stand in for a family or a character nothing in the project has. The build names each one it uses. |
build.slides
The page and type of a slide deck (PDF and slides).
| Key | Type | Default | Meaning |
|---|---|---|---|
|
|
string |
|
|
|
|
number |
|
Explicit points, overriding |
|
|
number |
|
The space around each slide's content, in points. What runs past it is clipped. |
|
|
string |
|
The family a slide's text is set in when nothing says otherwise. |
|
|
number |
|
The size a slide's text is set at, in points. |
|
|
boolean |
|
Draws |
|
|
string |
|
Text in the bottom-left corner of every slide. |
|
|
string |
|
A full-bleed colour for every slide; a slide's own style overrides it. |
|
|
string |
|
The colour of the numbers and the footer. Unset, it flips between dark and light on each slide's background. |
|
|
string | the project's name | The file written. |
|
|
list of paths, boolean |
|
As for |
dev
The development server, wf serve (Command line).
| Key | Type | Default | Meaning |
|---|---|---|---|
|
|
integer |
|
The port |
|
|
boolean |
|
Rebuilds on a save, reloads open tabs, and draws a failed build's error over the page. |
motion
What an animation does when the element says nothing (Motion defaults).
| Key | Type | Default | Meaning |
|---|---|---|---|
|
|
string | unset |
How long an animation runs: |
|
|
string | unset |
How it is paced: a CSS timing function, or a token such as |
meta
What every page's head carries: its fallbacks, its search and sharing tags, and the other origins the content security policy allows.
| Key | Type | Default | Meaning |
|---|---|---|---|
|
|
string | the project's name | The title a page falls back to when it declares none. |
|
|
string |
|
The description a page falls back to when it declares none. |
|
|
language tag |
|
The document's language: |
|
|
string |
|
The site's absolute address, such as |
|
|
string |
|
The name a link preview shows, and the site's owner in the structured data. |
|
|
|
|
Whether the site belongs to an organisation or a person: the JSON-LD node the site is published by (Search and link previews). |
|
|
list of URLs |
|
The owner's profiles elsewhere, as its |
|
|
string |
|
A person's |
|
|
map |
|
More about the owner, as schema.org properties merged into its node as written: |
|
|
file |
|
The sharing image for pages that set none. For an image in |
|
|
string |
|
What that image shows, as |
|
|
file |
|
The icon a browser tab shows: a file in |
|
|
file |
|
The icon a phone puts on its home screen: a 180×180 PNG in |
|
|
boolean |
|
Writes |
|
|
list of URLs |
|
Web-font stylesheets to link, each with a |
|
|
list of paths |
|
Files on this site to fetch with the page, ahead of the stylesheets: a font a project |
|
|
list of paths or URLs |
|
Extra stylesheets to link ahead of |
|
|
list of scripts |
|
Libraries to load before the project's own scripts (below). Their origins join the policy (JavaScript interop). |
|
|
map of URL to hash |
|
Subresource-integrity hashes of external assets, by URL. |
|
|
list of origins |
|
Origins a page may send requests to besides its own — an API elsewhere, an analytics endpoint — as the policy's |
|
|
list of origins |
|
Origins a page may load images from besides its own and |
|
|
list of origins |
|
Origins a page may embed in a frame besides its own — a video player, a map — as the policy's |
|
|
boolean |
|
The pages compile WebAssembly: |
|
|
boolean |
|
A script on the page writes |
An entry of connect, img or frame that has a path, or that is a keyword, is E111. Allow other origins covers these settings and wasm and style_elements.
An entry of meta.scripts takes one of these forms:
| Form | Meaning |
|---|---|
|
|
A classic script, linked |
|
|
An ES module, whose exports are put on |
|
|
A script whose names |
|
|
A script nothing waits for — analytics — loaded without holding up the page's code. |
|
|
A script the page asks for only once it has loaded and painted. |
|
|
A script the page asks for only once the reader has accepted it in a |
theme
Which theme the site uses, and token values set over it (Design tokens).
| Key | Type | Default | Meaning |
|---|---|---|---|
|
|
string | unset |
Which |
|
|
string | unset |
The |
|
|
|
|
|
|
|
map of token to value |
|
Token values applied over the theme, for a pipeline to supply — a colour a deploy injects. |
i18n
The project's translations. Absent, the project has one language.
{ "i18n": { "default_locale": "en", "locales": ["en", "ar"], "dir": "src/translations" } }
| Key | Type | Default | Meaning |
|---|---|---|---|
|
|
language tag |
|
The locale a page opens in, and the one a message falls back to when the current locale has no translation of it. |
|
|
list of language tags |
|
Every locale; one JSON file each, under |
|
|
string |
|
The folder the translation files are in. |
|
|
boolean |
|
Translates by the words themselves: each string a reader sees is its own key. |
See also: Translate a site.
env and public_env
Values the program reads as env.NAME, and which of them may reach the browser.
| Key | Type | Default | Meaning |
|---|---|---|---|
|
|
map |
|
Values read as |
|
|
list of names |
|
The |
See also: Environments and secrets.
offline
The service worker that stores the site for when the network is gone. Added in 4.1. Absent, no service worker is written.
{ "offline": { "precache": ["/", "/docs/*"], "fallback": "/offline", "cache": { "/api/*": "network-first" }, "sync": true } }
| Key | Type | Default | Meaning |
|---|---|---|---|
|
|
list of globs |
|
The routes a first visit stores; |
|
|
string |
|
A page's path, shown for a route that was not stored. |
|
|
map of glob to strategy |
|
How paths the build did not write are fetched: |
|
|
boolean |
|
Keeps a write safe to send twice — a |
See also: Work offline.
apis
The services wf api keeps from an OpenAPI spec, by name. Added in 7.0. wf api add writes an entry; wf api sync rewrites each service's generated/ folder from its spec; wf api check and wf check (N07) say when that folder is behind.
{ "apis": { "Backend": { "spec": "openapi.json", "out": "src/api/backend", "skip": [] } } }
| Key | Type | Default | Meaning |
|---|---|---|---|
|
|
string | — | The OpenAPI 3.0 or 3.1 spec, JSON or YAML, a file in the project. |
|
|
string |
|
The folder its |
|
|
list of names |
|
Operations left out, by the name they would have — one whose body or answer the language cannot read. |
lints
What a finding counts as, by its code or its family: "off", "warn" or "error". A code's setting wins over its family's.
{ "lints": { "A11": "off", "U": "error", "R01": "warn" } }
You can turn a warning off or make it an error. You can lower an error only when it cannot ship a broken page:
R01— a link to a route that is missing;C02— a prop the component does not declare;S04— two pages on one route;I01,I02,I04— a message that shows its key or a placeholder.
Asking to lower any other error is itself refused (E111), and so is a key that is not a code or a family. There is no loose mode: what 7.0 refuses — Any and Map (T23, T24), an untyped state or parameter, a match with no .failed arm (T21), a removed request form (N08) — stays an error, and wf migrate carries a 6.x project across. To accept one finding on one line instead, write a // wf-allow(CODE) comment; the same rule applies. Every code is listed in Diagnostics.