assets

INTERNAL_KEY: '_assets'

---

What it does

The assets module is the bridge between Eleventy's template system and the asset processors. It registers js and css as template formats, gates them with compile guards (filters that decide which files get processed), watches the assets directory for changes, and exposes two inline filters for embedding bundles directly in a template.

esbuild handles JS, PostCSS handles CSS. Both ship with Baseline.

Active when

Always. The assets module is always loaded.

Lifecycle

Build-time only. The module registers template formats, compile guards, a watch target, and the inline filters. It does no cascade-time or transform-time work.

---

How it works

---

Defaults

Options

PostCSS has no plugin-level options. Configure it through your own postcss.config.js. See Customise the assets pipeline for the recipe.

---

JS processor: esbuild

The JS processor bundles a JavaScript file and returns the compiled text. A pure function with no Eleventy knowledge: takes a path, returns a string.

At the plugin level, override esbuild defaults through options.assets.esbuild:

import baseline, { config as baselineConfig } from '@apleasantview/eleventy-plugin-baseline';
import settings from './src/_data/settings.js';

/** @param {import("@11ty/eleventy").UserConfig} eleventyConfig */
export default async function (eleventyConfig) {
	eleventyConfig.addPlugin(
		baseline(settings, {
			assets: {
				esbuild: {
					minify: process.env.ELEVENTY_ENV === 'production',
					target: 'es2017'
				}
			}
		})
	);
}

export const config = baselineConfig;

These apply to both compiled entry points and the inline filter, unless overridden per call.

Per call, the inlineESbuild filter accepts an options object that merges with the defaults:

{% set jsPath = _baseline.paths.assets ~ "js/inline-example.js" %}
{{ jsPath | inlineESbuild({ minify: false, target: "es2017" }) | safe }}

The filter is not limited to the assets directory: pass any absolute path. In Markdown, keep the call unindented and on its own lines so the <script> tag is treated as raw HTML, and pipe through | safe so Nunjucks does not escape it.

On error, the processor logs and returns /* Error processing JS */ so the build does not break.

---

CSS processor: PostCSS

The CSS processor runs a CSS file through PostCSS and returns the compiled text. Pure function, same shape as the JS processor.

It does not take plugin-level options. Configure it through postcss.config.js at your project root. See Customise the assets pipeline for the steps.

The inlinePostCSS filter wraps any CSS file in <style> tags:

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

Same Markdown caveat: keep the call unindented, pipe through | safe. Useful for critical CSS that should render before the main stylesheet loads.

On error, the processor logs and returns /* Error processing CSS */.

---

Tips

• Only index.js and index.css are compiled. Use them as entry points; reach everything else through import and @import.
• The watch target covers images too, so editing an SVG or PNG triggers a reload without extra config.
• The bundled PostCSS fallback is a sensible starting point. You only need your own postcss.config.js when you want to customise plugins.
• Inline filters are useful for small critical-path assets. Avoid inlining anything large; the bundle ends up duplicated on every page.

---

Peer deps

esbuild and postcss. Both ship with Baseline.

See also

• Image shortcode reads _baseline.paths.assets for default lookups.
• Filters reference lists inlineESbuild and inlinePostCSS alongside the rest.
• Customise the assets pipeline
• Tutorial: assets pipeline