Configuration

Every key of webfluent.app.json, its default, and what it changes.

A project's settings live in webfluent.app.json beside src/. Every key is optional except name, so the smallest config is:

json

{ "name": "my-site" }

A key the build does not know is reported with a warning — and the key it most likely meant, so "defaultLocale" says to write default_locale — rather than silently ignored (4.1).

The defaults

This is what a config with only a name means. i18n and offline are absent unless you add them.

json

{
  "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": []
  },
  "motion": { "duration": null, "easing": null },
  "env": {},
  "lints": {},
  "public_env": []
}

wf init writes a shorter file and turns build.csp on.

The project

The project
Key	Default	Meaning
`name`	—	The only required key. The site's name, the PDF's file name when none is given, and `meta.title`'s fallback.
`version`, `author`	`"0.1.0"`, `""`	Yours; nothing in the build reads them.

build

build
Key	Default	Meaning
`output`	`"./build"`	Where the build is written, relative to the project.
`output_type`	`"spa"`	`spa` (a website), `pdf`, `slides` or `elements` (chapter 33).
`ssg`	`false`	Pre-render every page to its own HTML (chapter 26).
`base_path`	`""`	The sub-path the site is served under, such as `"/docs"`. Every link and asset is prefixed.
`clean_urls`	unset	How a route's address avoids a redirect on a host that adds the slash: `"file"` also writes `contact.html` beside `contact/index.html`; `"directory"` names every route `/contact/` in canonical links, the sitemap and links to pages (chapter 27).
`split`	`true`	One script and stylesheet chunk per page, loaded when its route shows.
`minify`	`true`	Strip comments and whitespace from the scripts and stylesheets.
`sourcemap`	`false`	Write a source map beside the bundle.
`compress`	`true`	Write a `.gz` beside every text output over a kilobyte.
`runtime`	`"auto"`	`auto` ships the runtime modules the program reaches; `full` ships every one, for a hand-written script that calls `WF` (chapter 32).
`csp`	`false` (`true` in a project `wf init` makes)	Emit a Content-Security-Policy and `_headers`, and check the output against the policy (chapter 23).
`budget`	`{}`	A gzipped size each named output should stay under: `{ "app.js": "40 kB" }`. Over it, the build warns.
`elements`	`[]`	With `output_type: "elements"`, the components to publish as custom elements.
`media`	below	The image pipeline.
`pdf`, `slides`	below	The paper outputs.

build.media

build.media
Key	Default	Meaning
`formats`	`["webp"]`	The formats every `image` is written in, as well as its original.
`widths`	`[480, 960, 1440, 1920]`	The widths written, where smaller than the original.
`quality`	`78`	The encoding quality, 1–100.
`pipeline`	`true`	`false` copies images as `public/` does, without resizing.

build.pdf

build.pdf
Key	Default	Meaning
`page_size`	`"A4"`	`A4`, `A3`, `A5`, `A6`, `Letter`, `Legal`, `Tabloid`, `Executive`, or two lengths (`"210mm 297mm"`). A `Document(size:)` overrides it.
`margins`	`72` each	`top`, `bottom`, `left`, `right`, in points (72 to the inch); the header and footer are drawn in them.
`default_font`	`"Helvetica"`	The document's family when its sheets name none: a standard name (`Helvetica`, `Times`, `Courier` — Liberation, built in) or a family under `fonts/`.
`default_font_size`	`12`	In points; `rem` in a style is this size.
`output_filename`	the project's name	The file written.
`fonts`	`[]`	Font files or directories beside the project's `fonts/`, `src/fonts/` and `public/fonts/`, which are always read.
`system_fonts`	`true`	Whether this machine's fonts may stand in for a family or a character nothing in the project has; the build names each one used.

build.slides

build.slides
Key	Default	Meaning
`size`	`"16:9"`	`16:9` (960 × 540 pt), `4:3`, `A4-landscape`, or `"WIDTHxHEIGHT"` in points.
`width`, `height`	`null`	Explicit points, overriding `size`.
`margin`	`60`	The space around each slide's content; what runs past it is clipped.
`default_font`, `default_font_size`	`"Helvetica"`, `24`	The deck's text.
`show_slide_numbers`	`false`	`n / total` in the bottom corner.
`footer_text`	`null`	Text in the bottom-left of every slide.
`background_color`	`null`	A full-bleed colour for every slide.
`chrome_color`	`null`	The colour of the numbers and footer; unset, it flips between dark and light on the slide's background.
`output_filename`	the project's name	The file written.
`fonts`, `system_fonts`	`[]`, `true`	As for `build.pdf`.

dev

dev
Key	Default	Meaning
`port`	`3000`	The port `wf serve` listens on.
`hot_reload`	`true`	Rebuild on a save, reload open tabs, and draw a failed build's error over the page.

motion

motion
Key	Default	Meaning
`duration`	unset	How long an animation runs when the element does not say: `"180ms"`.
`easing`	unset	How it is paced: a CSS timing function, or a token such as `"$ease-standard"`.

meta

meta
Key	Default	Meaning
`title`, `description`	the name, `""`	What a page falls back to when it declares none.
`lang`	`"en"`	The document's language.
`site_url`	`""`	The absolute address. Without it, canonical links, the sitemap's URLs and absolute sharing URLs are left out rather than guessed.
`site_name`	`""`	The name a link preview shows, and the site's owner in the structured data.
`owner`	`"organization"`	Whether the owner is an `"organization"` or a `"person"` — the JSON-LD node the site is published by (chapter 27).
`same_as`	`[]`	The owner's profiles elsewhere, as its `sameAs`.
`job_title`	`""`	A person's `jobTitle`.
`owner_details`	`{}`	More of the owner, as schema.org properties merged into its node as written: `alternateName`, `email`, `worksFor`, `alumniOf`, `knowsAbout`, `logo`… The node's `@type`, `@id`, `name`, `url`, `jobTitle` and `sameAs` come from the settings above (`E111`).
`image`	`""`	The sharing image for pages that set none; one in `public/` has its size read into `og:image:width`/`height`.
`image_alt`	`""`	What that image shows: `og:image:alt` and `twitter:image:alt`. A page's `image_alt:` wins.
`favicon`	`""`	The icon a tab shows: a file in `public/` — an SVG scales to every size — or a URL.
`touch_icon`	`""`	The icon a phone puts on its home screen: a 180×180 PNG in `public/`. iOS reads this, not an SVG `favicon`.
`sitemap`	`true`	Write `sitemap.xml` and `robots.txt`.
`fonts`	`[]`	Web-font stylesheet URLs to link, each with a `preconnect`; their origins join the policy.
`preload`	`[]`	Files on this site to fetch with the page, ahead of the stylesheets: a font a project `.css` file's `@font-face` names, the first screen's picture. `as` comes from the extension (a font is also `crossorigin`); a file on another origin is `E111` (chapter 27).
`stylesheets`	`[]`	Extra stylesheets to link ahead of `styles.css`: a file in `public/` or a URL.
`scripts`	`[]`	Libraries to load before the project's own scripts: a URL or a file in `public/`, or `{ "src", "module": true, "as": "Name" }` for an ES module, or `{ "src", "globals": ["Chart"] }` to call a library's names from `.wf`. `"async": true` loads one nothing waits for — analytics — without holding up the page's code, and `"load": "after"` asks for it only once the page has loaded and painted. Their origins join the policy (JavaScript interop).
`connect`	`[]`	Origins a page may send requests to besides its own — an API elsewhere, an analytics endpoint — as the policy's `connect-src`: `"https://api.example.com"`, `"https://*.google-analytics.com"`. An entry with a path or a keyword is `E111` (chapter 23).
`img`	`[]`	Origins a page may load images from besides its own and `data:` — a CDN, a tag's tracking pixel — as the policy's `img-src`: `"https://images.example.com"`, `"https://www.googletagmanager.com"`. An entry with a path or a keyword is `E111` (chapter 23).
`integrity`	`{}`	Subresource-integrity hashes of external assets, by URL.

theme

theme
Key	Default	Meaning
`name`	unset	Which `theme` declaration is the site's. A project with exactly one need not name it.
`dark`	unset	The theme that stands in for dark mode (chapter 15).
`builtin`	`"full"`	`full` ships the built-ins' designed look; `structural` only their layout and mechanics.
`tokens`	`{}`	Token values on top of the theme, for a pipeline to supply.

i18n

json

{ "i18n": { "default_locale": "en", "locales": ["en", "ar"], "dir": "src/translations" } }

i18n
Key	Default	Meaning
`default_locale`	`"en"`	The locale a page opens in.
`locales`	`["en"]`	Every locale; one JSON file each.
`dir`	`"src/translations"`	Where the files are.

Chapter 21.

env and publicenv

env and publicenv
Key	Default	Meaning
`env`	`{}`	Values read as `env.NAME`, fixed at build time. A `.env` file and the shell add to them.
`public_env`	`[]`	Names a page may read beyond those beginning `PUBLIC_`.

Chapter 30.

offline

4.1. Absent, no service worker is written.

json

{ "offline": { "precache": ["/", "/docs/*"], "fallback": "/offline", "cache": { "/api/*": "network-first" }, "sync": true } }

offline
Key	Default	Meaning
`precache`	`["/"]`	The routes a first visit stores, as globs; `"*"` for every route.
`fallback`	`null`	A page's path, shown for a route that was not stored.
`cache`	`{}`	How paths the build did not write are fetched: `network-first`, `cache-first`, `stale-while-revalidate` or `network-only`.
`sync`	`false`	Keep writes made offline and send them later.

Chapter 19.

lints

What a finding counts as, by its code or its family — "off", "warn" or "error", the code first, then the family:

json

{ "lints": { "A11": "off", "U": "error", "R01": "warn" } }

A warning may be turned off or made an error. An error may be lowered only when it cannot ship a broken page — R01 (a link to a route that is missing), C02 (a prop nothing reads), S04 (two pages on one route) and I01, I02, I04 (a message that shows its key or a placeholder); asking to lower any other is itself refused, and so is a key that is no code or family. Every code is in Diagnostics. One finding on one line is allowed with a // wf-allow(CODE) comment instead, under the same rule.

On this page

The defaults The project build dev motion meta theme i18n env and publicenv offline lints

Edit this page

Components reference

Checked by the test suite

Every code block in the guide is parsed, checked and type-checked on each release.