GioJSdocs
ReleasesGitHub ↗
On this page

[css]

How stylesheets are processed: path-served app/*.css, minification of production CSS, and critical CSS inlining.

gio.toml
[css]
minify = false              # readable production CSS while debugging

Imported CSS (import './globals.css', CSS Modules) is part of the module graph and is always bundled by the worker; no key here turns it off. See CSS & Styling.

Reference

KeyDefaultDescription
enabledbooleantrueServe every non-module .css file under app/ at its path (app/globals.css at /globals.css), processed by Lightning CSS once at startup and kept in memory. Imported CSS is unaffected. Off, there is also no critical CSS, which is extracted from the path-served globals.css.0 / false / empty: app/*.css is not served by path
minifybooleantrueMinify production CSS: the path-served stylesheets (Lightning CSS) and the bundled route stylesheets (esbuild). Development never minifies. gio build standalone bakes the route stylesheets at build time, so there the gio.toml the build reads decides.0 / false / empty: Production CSS stays readable
critical_extractionbooleantrueOn cached pages that link no imported route stylesheet, inline the rules of app/globals.css the page uses and load the full file without blocking render.0 / false / empty: No inlined critical CSS

Behavior

  • The server hands minify to the Node worker in the GIO_CSS_CONFIG environment variable. It is one of the settings the deployment id covers, so changing it drops persisted pages, which link the stylesheets it builds. enabled and critical_extraction are covered too: the server inlines critical CSS into the pages it persists, so turning either off drops them instead of serving their inlined CSS until they expire.
  • Path-served stylesheets have no content hash in their URL, so they are sent with Cache-Control: public, max-age=0, must-revalidate and a strong ETag.
  • Critical CSS is skipped on pages that import CSS: their stylesheet (often globals.css itself) is already linked, and loading the file a second time would let it override the route's own rules. Under a CSP with nonces, the snippet's inline <style> and its loader script carry the nonce.

No key in this section logs a warning.

Examples

Only imported CSS

An app that imports all of its CSS needs no path-served copies:

gio.toml
[css]
enabled = false

Debug production CSS

gio.toml
[css]
minify = false
critical_extraction = false

Good to know

  • *.module.css files are never served by path: their class names only exist in the import pipeline.
  • In development, editing a stylesheet re-processes the path-served copies and restarts the worker.
  • [css] engine from earlier docs is refused: Lightning CSS is the only engine (unknown key `css.engine` - Lightning CSS is the only CSS engine. Remove the key).

Version history

VersionChanges
v0.1.0-beta.8minify also covers the bundled route stylesheets (the server passes [css] to the worker in GIO_CSS_CONFIG); enabled is documented as covering path-served stylesheets only. engine is rejected. enabled and critical_extraction are part of the deployment id.
v0.1.0-beta.1Introduced with enabled, minify and critical_extraction.