Add a custom stem

Problem

You want discovery to pick up a file named page.css next to template.djx, or vendor.js inside a component folder, in addition to the default stems.

Solution

Register the stem through next.static.discovery.default_stems in AppConfig.ready.

Walkthrough

Register the stem under the appropriate role.

notes/apps.py

from django.apps import AppConfig
from next.static.discovery import default_stems

class NotesConfig(AppConfig):
    name = "notes"

    def ready(self) -> None:
        default_stems.register("template", "page")
        default_stems.register("component", "vendor")

The first argument is the role, one of template, layout, or component. The second argument is the new stem.

Ship a file with the new stem.

notes/pages/

page.py
template.djx
page.css

Discovery now records page.css as a css asset owned by the page, because page is a registered stem under the template role and .css is the extension of the css kind.

Stem and kind pairing

A new stem participates in every registered kind. After registering vendor under the component role, discovery looks for vendor.css, vendor.js, and vendor.mjs inside component folders.

Verification

Editing apps.py restarts the dev server, so the new stem registration is live on the next boot. Reload a page that uses the file and confirm the asset appears in the rendered HTML.

Confirm the staticfiles finder picks the new file up.

shell

uv run python manage.py findstatic next/index.css

The finder maps a template-directory asset to next/<logical_name><suffix>. The logical name is the template directory relative to its page root, and a root template has the logical name index. The stem does not appear in the static path, so page.css next to the root template.djx resolves under next/index.css.

See also

See also

Custom stems for the mechanics. Co-located files for the default stems.