assets-postcss

Note: The options API is still evolving; expect tweaks as the project grows.

What it does

assets-postcss processes a CSS file through PostCSS and returns the compiled text. It's a pure function — no Eleventy knowledge, no side effects. assets-core calls it during the build for entry files and through the inlinePostCSS filter for inline styles.

Defaults

• Config: your project's postcss.config.js (resolved from the project root).
• Fallback: if no config is found, Baseline uses a bundled config with postcss-import, postcss-preset-env, and cssnano (production only).
• Config caching: the PostCSS config is loaded once and cached for the lifetime of the process. Restart Eleventy to pick up config changes.

Options

assets-postcss has no plugin-level options — it's configured through your postcss.config.js. See the custom PostCSS config guide for details.

How it works

1. Reads the CSS file from disk (fs.readFile).
2. Loads the PostCSS config — your project's postcss.config.js if one exists, otherwise the bundled fallback. The config is cached after the first load.
3. Runs postcss(plugins).process() with the loaded config and the file path as from (so relative @import paths resolve correctly).
4. Returns the processed CSS text. Eleventy (via assets-core) writes the final file.

On error, logs to console and returns a /* Error processing CSS */ comment so the build doesn't break.

Inlining CSS

The inlinePostCSS filter processes any CSS file you point it at — not limited to the assets directory. It wraps the result in <style> tags.

{% set cssPath = _baseline.assets.input ~ "css/critical.css" %}
{{ cssPath | inlinePostCSS | safe }}

In Markdown, keep the call unindented and on its own lines so the <style> is treated as raw HTML. Use | safe so Nunjucks doesn't escape the tags.

Tips

• Only index.css files are compiled as entry points. Use them as the front door; @import everything else from there.
• The bundled fallback config is a sensible starting point — you don't need your own postcss.config.js unless you want to customize plugins.
• The inline filter is useful for critical CSS that should render before the main stylesheet loads.
• See the Assets Pipeline Quickstart for an end-to-end example.

Peer deps

postcss (included in Baseline's dependencies). Plugins come from your postcss.config.js or the bundled fallback.