Static Assets Overview¶

The static pipeline finds CSS, JS, and module files that live next to pages and components. It deduplicates them across the request and injects link and script tags into placeholder slots inside the layout. This page covers the four moving pieces of the pipeline and traces a single asset from disk to the rendered HTML.

The Pipeline ¶

Four parts make up the pipeline.

Discovery.: AssetDiscovery produces StaticAsset records from files matching a registered stem and kind.
Collector.: StaticCollector accumulates and deduplicates the assets touched by the current render.
Backend.: A StaticBackend resolves on-disk paths into URLs and renders the tags. StaticFilesBackend is the bundled one.
Placeholder slots and template tags.: {% collect_styles %} and {% collect_scripts %} mark the slots the static manager fills after the page renders.

StaticAsset ¶

StaticAsset is a frozen dataclass with four fields.

url.: The public URL of the asset. Empty for inline assets.
kind.: The asset kind, such as css, js, or module.
source_path.: The path of the co-located file on disk, or None for inline and external assets.
inline.: The pre-rendered inline body, or None for URL assets.

url and inline are mutually exclusive. A URL asset carries a non-empty url and a None inline. An inline asset carries a None or empty url and a non-empty inline body.

Asset Kinds ¶

A kind binds a file extension to a placeholder slot and a backend renderer method. The framework registers the two placeholder slots and three asset kinds at startup through register_defaults.

Kind	Extension	Slot	Renderer method
`css`	`.css`	`styles`	`render_link_tag`
`js`	`.js`	`scripts`	`render_script_tag`
`module`	`.mjs`	`scripts`	`render_module_tag`

The kind registry is next.static.default_kinds. Projects register additional kinds through default_kinds.register. See Asset Kinds for the registration recipe.

A Single Asset From Disk to HTML ¶

A file named component.css next to component.djx reaches the browser in one pass. Discovery records it as a css StaticAsset because component is a registered stem and .css is the css kind extension. A render that uses the component adds the asset to the collector, which deduplicates it. After the page renders, the static manager replaces the styles slot token emitted by {% collect_styles %} with the link tags produced by render_link_tag on the active backend. render_link_tag resolves the on-disk path to a public URL through Django staticfiles, so manifest hashing and CDN settings apply to the emitted tag.

The same flow applies to component.js (kind js, classic script) and component.mjs (kind module, ECMAScript module), which both land in the scripts slot emitted by {% collect_scripts %}. The extension picks the kind, so a file named component.js never renders through render_module_tag. Static Pipeline traces the pipeline step by step.

Stems and Owners ¶

Discovery recognises files by stem. A stem is the filename without the extension.

Role	Default stem	Matches
`template`	`template`	`template.css`, `template.js` next to `template.djx`
`layout`	`layout`	`layout.css`, `layout.js` next to `layout.djx`
`component`	`component`	`component.css`, `component.js` inside a component folder

The stem registry is default_stems, which lives at next.static.discovery rather than the package root. Projects register extra stems through default_stems.register. See Custom Stems.

Where Assets Live ¶

Co-located Files shows the directory layout where co-located assets sit next to pages, layouts, and components.

Hot Reload ¶

Co-located assets are not watched by the autoreloader. The collector re-runs discovery on every request, so a saved or added asset is picked up on the next page load without a process restart. A change to page.py or component.py does restart the process through the normal Python reloader. A .djx template change is likewise picked up on the next request without a restart.

Production Build ¶

In production, collectstatic copies every registered asset into STATIC_ROOT under the next/ namespace. The framework hooks into the staticfiles finders through NextStaticFilesFinder so Django sees co-located assets.

See Static Files in Production for production guidance.

Public API Touchpoints ¶

Static Reference is the full reference for the pipeline’s public names.