Static Reference

Module Summary

next.static exposes the asset discovery, the request-scoped collector, and the backend chain. It also exposes the kind and placeholder registries, the next.min.js script builder, the staticfiles finder, and the JS context serializer.

Public API

Collector

Collector, dedup strategies, JS context policies, and placeholder slots.

Rendering flows are stateful. Every HTTP request spins up a fresh collector that rides along in the template context, absorbs every {% use_style %}, {% #use_script %}, co-located template.css, and styles or scripts list entry, then hands the accumulated set back to the static manager when the template finishes.

The collector does not hardcode deduplication or merge semantics. Strategy objects plug in at construction time, so users can swap URL-based dedup for content-hash dedup or replace the default first-wins JS-context merge with a deep-merge policy without touching the collector source.

The collector is also fully type-agnostic. Each asset routes to a slot named in KindRegistry, and the buckets live in a slot-keyed dictionary on the collector. There is no built-in knowledge of css, js, or any other specific kind here.

class next.static.collector.DedupStrategy(*args, **kwargs)

Key-based dedup strategy consumed by the static collector.

Implementations return a hashable value that uniquely identifies an asset for deduplication. The collector ignores any asset whose key was already recorded.

key(asset: StaticAsset) → Hashable

Return a hashable key identifying the asset for dedup.

__init__(*args, **kwargs)

class next.static.collector.UrlDedup

Dedupe inline assets by rendered body and URL-form assets by URL.

This is the process-wide default. It mirrors the behavior of the original hand-rolled dedup built into the earlier collector.

key(asset: StaticAsset) → Hashable

Return an inline-form key or a URL-form key based on the asset.

class next.static.collector.HashContentDedup

Dedupe URL-form assets by sha256 of their disk content.

This is useful in production builds where identical CSS may be emitted under different hashed filenames by a manifest storage. The strategy falls back to URL-based dedup when the source_path is missing.

__init__() → None

Initialise an empty per-path sha256 cache.

key(asset: StaticAsset) → Hashable

Hash the asset disk contents when available, otherwise fall back.

class next.static.collector.IdentityDedup

Disable deduplication so every registration yields a unique key.

__init__() → None

Initialise the monotonically increasing counter.

key(asset: StaticAsset) → Hashable

Return a unique incrementing key so dedup never triggers.

class next.static.collector.JsContextPolicy(*args, **kwargs)

Merge strategy for the collector JS context.

merge(existing: dict[str, Any], key: str, value: Any) → dict[str, Any]

Merge a new entry into the existing mapping and return it.

__init__(*args, **kwargs)

class next.static.collector.FirstWinsPolicy

Keep the first registration and silently ignore subsequent writes.

This is the default policy. Page-level context wins over component-level context when both register the same key.

merge(existing: dict[str, Any], key: str, value: Any) → dict[str, Any]

Write the value only when the key is absent from existing.

class next.static.collector.LastWinsPolicy

Overwrite the previous value with the latest registration.

merge(existing: dict[str, Any], key: str, value: Any) → dict[str, Any]

Assign the value under the key, overwriting any existing entry.

class next.static.collector.RaiseOnConflictPolicy

Raise KeyError when the same key is registered twice.

merge(existing: dict[str, Any], key: str, value: Any) → dict[str, Any]

Assign the value or raise when the key already exists.

class next.static.collector.DeepMergePolicy

Recursively merge dict values and override scalars with the latest value.

merge(existing: dict[str, Any], key: str, value: Any) → dict[str, Any]

Recursively merge dict values or assign the new one otherwise.

class next.static.collector.PlaceholderSlot(name: str, token: str)

Binding between a {% collect_* %} placeholder name and its token.

The name field identifies the slot. Assets routed to this slot by KindRegistry.slot(asset.kind) accumulate in the collector under this name. The token field is the HTML comment marker emitted by the matching template tag at render time and replaced by the static manager during injection.

name: str

token: str

__init__(name: str, token: str) → None

class next.static.collector.PlaceholderRegistry

Mutable registry of placeholder slots.

The registry ships empty. Framework bootstrap registers built-in slots such as styles and scripts, and user code registers additional slots with the same register call when introducing new asset destinations.

__init__() → None

Initialise an empty slot registry.

register(name: str, *, token: str) → None

Register the slot under its name with the given placeholder token.

A repeated call with the same token is idempotent. A repeated call with a different token raises ValueError so silent overrides cannot mask bugs.

get(name: str) → PlaceholderSlot | None

Return the slot registered under the given name or None.

__iter__() → Iterator[PlaceholderSlot]

Iterate over registered slots in registration order.

__len__() → int

Return the number of registered slots.

class next.static.collector.StaticCollector(*, dedup: DedupStrategy | None = None, js_context_policy: JsContextPolicy | None = None, js_serializer: JsContextSerializer | None = None)

Accumulate static asset references during a single page render.

The optional dedup argument plugs in a custom dedup strategy. The default is UrlDedup. The optional js_context_policy argument plugs in a custom merge strategy for the JS context. The default is FirstWinsPolicy, which ensures page-level context wins over component-level context.

Assets are added through the add method and later consumed by the static manager during injection. The collector has no knowledge of backends or rendering. It coordinates insertion order, deduplication, and JS context merging.

Buckets are keyed by slot name as resolved through KindRegistry. The collector does not hardcode any specific slot, so adding new asset kinds to the registry transparently produces new buckets.

__init__(*, dedup: DedupStrategy | None = None, js_context_policy: JsContextPolicy | None = None, js_serializer: JsContextSerializer | None = None) → None

Wire up dedup, JS-context policy, and JS serializer.

add(asset: StaticAsset, *, prepend: bool = False) → None

Add the asset unless its dedup key was already recorded.

Inline assets always append because their dedup key derives from the body. URL-form assets with prepend=True are inserted before existing append entries while keeping registration order among prepended items.

The asset routes to the bucket named by KindRegistry.slot(asset.kind). Unregistered kinds raise KeyError so misconfiguration surfaces immediately.

assets_in_slot(name: str) → list[StaticAsset]

Return collected assets for the named slot in insertion order.

Returns an empty list when nothing was registered for the slot. Callers must not mutate the returned list.

add_js_context(key: str, value: Any, *, serializer: JsContextSerializer | None = None) → None

Merge the value under the key through the JS-context policy.

Validates that value is serialisable by the active serializer before merging. Surfacing the failure here, at the registration site, gives a much better traceback than catching it at final page inject time. When serializer is supplied, the override validates this value and is recorded for the inject phase so the same key uses the same serializer end to end. The override does not leak into other keys.

js_context() → dict[str, Any]

Return the accumulated JS context.

Callers must not mutate the returned mapping.

js_context_serializers() → dict[str, JsContextSerializer]

Return the per-key serializer overrides recorded so far.

The returned mapping is empty when every key uses the global serializer. Callers must not mutate it.

Discovery

Discover co-located CSS/JS files and page and component module asset lists.

This module owns the filesystem side of the static pipeline. It walks layout chains, reads styles and scripts module lists, and pushes results onto a collector via the active backend.

The path-to-logical-name conversion lives on the PathResolver so both discovery and the staticfiles finder share the exact same mapping. The StemRegistry controls which filenames are auto-picked-up per role. It lets users teach the framework about new stems like page.css or panel.js without patching the core.

The BackendProvider protocol inverts the dependency direction. The discovery layer does not import the static manager directly. Any object exposing default_backend and page_roots satisfies the protocol, which makes unit-testing without a full manager trivial.

The provider contract requires that page_roots returns already resolved absolute paths. Both the static manager and the co-located finder satisfy this contract, which lets the discovery layer skip a round of resolution on every logical-name lookup.

class next.static.discovery.BackendProvider(*args, **kwargs)

Contract consumed by the asset discovery layer.

The static manager is the canonical implementation. Tests can pass any object exposing default_backend and page_roots without instantiating the full manager. Implementations must return resolved absolute paths from page_roots.

property default_backend: StaticBackend

Return the primary backend used for file registration.

page_roots() → tuple[Path, ...]

Return the configured page-tree roots as resolved absolute paths.

__init__(*args, **kwargs)

class next.static.discovery.StemRegistry

Map discovery role to registered filename stems.

Default roles and their stems are as follows. The template role maps to [“template”] and matches template.css or template.js. The layout role maps to [“layout”] and matches layout.css or layout.js. The component role maps to [“component”] and matches component.css.

Users may register extra stems during AppConfig.ready to teach discovery about new filenames.

Example:

default_stems.register("template", "page")

The example above teaches discovery to also pick up page.css or page.js alongside template.css or template.js.

DEFAULT_ROLES: tuple[str, ...] = ('template', 'layout', 'component')

__init__() → None

Seed the registry with the built-in template, layout, and component roles.

register(role: str, stem: str) → None

Add a stem under the given role, creating the role when missing.

stems(role: str) → tuple[str, ...]

Return registered stems for the role in registration order.

roles() → tuple[str, ...]

Return all registered roles in registration order.

class next.static.discovery.PathResolver(page_roots_provider: Callable[[], tuple[Path, ...]])

Resolve page root and logical names for page, layout, and component paths.

The resolver is shared between the asset discovery layer and the staticfiles finder so both layers produce identical logical names for the same on-disk location. The resolver assumes that the provider callable returns already resolved absolute page roots.

__init__(page_roots_provider: Callable[[], tuple[Path, ...]]) → None

Store the page-roots provider callable consulted on every lookup.

page_roots() → tuple[Path, ...]

Return the current tuple of page tree roots from the provider.

find_page_root(path: Path) → Path | None

Return the page tree root that contains the path, or None.

logical_name_for_template(template_dir: Path, page_root: Path | None) → str

Return the logical URL name for a page template directory.

The caller is expected to pass a resolved template_dir and a resolved page_root from find_page_root.

logical_name_for_layout(layout_dir: Path, page_root: Path | None) → str

Return the logical URL name for a layout directory.

The caller is expected to pass a resolved layout_dir and a resolved page_root from find_page_root.

class next.static.discovery.AssetDiscovery(provider: BackendProvider, *, resolver: PathResolver | None = None, stems: StemRegistry | None = None)

Detect co-located asset files and module-level asset list variables.

The provider argument supplies the active backend and the page tree roots. The optional resolver argument is a path resolver. The default resolver is backed by the provider. The optional stems argument is a stem registry. The default is the process-wide default_stems.

__init__(provider: BackendProvider, *, resolver: PathResolver | None = None, stems: StemRegistry | None = None) → None

Bind the provider and wire optional resolver and stems.

discover_page_assets(file_path: Path, collector: StaticCollector) → None

Collect layout, template, and module-level assets for a page file.

Assets are added from the outermost layout inward, then from the template directory, then from styles and scripts module lists declared in page.py.

discover_component_assets(info: ComponentInfo, collector: StaticCollector) → None

Collect co-located CSS, JS, and module asset lists for a component.

Backends

Pluggable backend contract and Django-staticfiles default implementation.

A static backend turns co-located asset paths into public URLs and renders them through one of its named renderer methods. The default backend delegates URL resolution to Django staticfiles, so manifest hashing, S3 storage, and CDN configuration from Django settings apply automatically.

The abstract StaticBackend only mandates register_file. Renderer methods are concrete on the default backend and selected per asset by KindRegistry.renderer(kind). Custom backends extend the surface by adding more named methods such as render_babel_script_tag and registering kinds that point to them.

A small factory builds backend instances from NEXT_FRAMEWORK[‘DEFAULT_STATIC_BACKENDS’] entries. The factory also emits the backend_loaded signal so user code may react to backend construction.

class next.static.backends.StaticBackend(config: Mapping[str, Any] | None = None)

Pluggable strategy for resolving asset files to URLs and rendering tags.

The constructor accepts the full backend entry from DEFAULT_STATIC_BACKENDS, which has the shape {“BACKEND”: “…”, “OPTIONS”: {…}}. The base class stores the mapping on the config property. Subclasses are free to read any keys they expose to users.

The only abstract requirement is register_file. Renderer methods are added by subclasses and selected per asset through KindRegistry.renderer(kind). The default backend below ships render_link_tag and render_script_tag for the built-in css and js kinds. Custom backends register additional kinds and expose matching methods.

__init__(config: Mapping[str, Any] | None = None) → None

Store the raw config mapping for subclasses to read.

property config: Mapping[str, Any]

Return the backend entry supplied at construction time.

abstractmethod register_file(source_path: Path, logical_name: str, kind: str) → str

Register a co-located asset file and return its public URL.

The source_path argument is the absolute path to the source file on disk. The logical_name argument is the path without an extension, for example “about” or “components/card”. The kind argument must be a kind registered in the default kind registry. The method raises RuntimeError when the asset cannot be resolved to a URL.

class next.static.backends.StaticFilesBackend(config: Mapping[str, Any] | None = None)

Resolve co-located asset URLs through Django staticfiles.

Assets live in the next/ staticfiles namespace so manifest storage, S3 storage, and CDN settings apply automatically.

Two option keys are recognised in the backend entry. The css_tag key sets a format string for <link> tags. It must contain the {url} placeholder. Extra attributes such as crossorigin or integrity can be baked directly into the template. The js_tag key sets a format string for <script> tags. The same placeholder rules apply. Attributes such as defer or async are added by writing them into the template.

__init__(config: Mapping[str, Any] | None = None) → None

Read tag templates from the OPTIONS mapping and prime caches.

register_file(source_path: Path, logical_name: str, kind: str) → str

Return the staticfiles URL for next/<logical_name><suffix>.

The suffix is taken from source_path.suffix, so a single kind can serve multiple file extensions if a custom backend wishes to. Result is cached per (logical_name, suffix). Missing entries in the staticfiles manifest are reported as RuntimeError with a hint about running collectstatic.

render_link_tag(url: str, *, request: HttpRequest | None = None) → str

Return a link tag built from the configured css_tag template.

The request argument is accepted for contract compatibility and ignored by the default backend.

render_script_tag(url: str, *, request: HttpRequest | None = None) → str

Return a script tag built from the configured js_tag template.

The request argument is accepted for contract compatibility and ignored by the default backend.

render_module_tag(url: str, *, request: HttpRequest | None = None) → str

Return a module script tag built from the configured module_tag template.

The request argument is accepted for contract compatibility and ignored by the default backend.

class next.static.backends.StaticsFactory

Build static backend instances from configuration dicts.

DEFAULT_BACKEND: ClassVar[str] = 'next.static.StaticFilesBackend'

classmethod create_backend(config: Mapping[str, Any]) → StaticBackend

Instantiate the backend class named by config[‘BACKEND’].

Raises TypeError when the configured class is not a subclass of StaticBackend.

Assets

Value objects and kind registry for static assets.

This module holds the leaf building blocks of the static subsystem. It defines a frozen value object for a single asset reference and a mutable registry that maps asset kinds to file extensions, placeholder slots, and renderer method names. The module has no internal dependencies and is safe to import before the Django app registry is ready.

The registry ships empty. Built-in kinds such as css and js are registered by the framework bootstrap layer through the same public register call that user code uses to teach the framework about new file types like jsx or wasm. Core code never special-cases any particular kind.

class next.static.assets.StaticNamespace

Namespace constants used when building staticfiles URL paths.

The NEXT constant is the top-level directory under which the framework publishes co-located assets inside the Django staticfiles tree. Public URLs have the form /static/next/<logical_name>.<ext>.

NEXT: Final = 'next'

class next.static.assets.StaticAsset(url: str, kind: str, source_path: Path | None = None, inline: str | None = None)

Immutable record describing one asset reference.

The collector populates instances of this class during page render. A URL form carries a non-empty url and an optional source_path pointing at the co-located file on disk. A block form carries a pre-rendered inline body and leaves url empty. The kind field must match a kind registered in the active KindRegistry.

url: str

kind: str

source_path: Path | None

inline: str | None

__init__(url: str, kind: str, source_path: Path | None = None, inline: str | None = None) → None

class next.static.assets.KindRegistry

Mutable registry mapping asset kinds to extension, slot, and renderer.

The registry ships empty. Bootstrap code registers built-in kinds such as css and js through register, and user code registers additional kinds the same way during AppConfig.ready.

Each registration carries three pieces of information.

The extension field is the file suffix associated with the kind. Discovery walks every registered kind and looks for files matching {stem}{extension} next to each template, layout, or component.

The slot field is the name of the placeholder slot that buckets this asset at render time. Slots are owned by a sibling PlaceholderRegistry and identify where the rendered tags land in the final HTML.

The renderer field is the method name that the configured static backend exposes for rendering asset URLs of this kind. The manager looks the method up on the active backend with getattr per asset.

Example usage during framework bootstrap.

Example:

default_kinds.register(
    "css",
    extension=".css",
    slot="styles",
    renderer="render_link_tag",
)

__init__() → None

Initialise an empty registry.

register(kind: str, *, extension: str, slot: str, renderer: str) → None

Register an asset kind and its dispatch metadata.

The kind argument must be a non-empty Python identifier. The extension argument must begin with a dot. The slot and renderer arguments must be non-empty strings. Any other input raises ValueError. A repeated call with identical parameters is idempotent. A repeated call with different parameters raises ValueError so silent re-registrations cannot mask bugs.

extension(kind: str) → str

Return the file extension registered for the given kind.

Raises KeyError when the kind has not been registered.

slot(kind: str) → str

Return the placeholder slot name registered for the given kind.

renderer(kind: str) → str

Return the backend method name registered for the given kind.

kind_for_extension(extension: str) → str | None

Return the kind registered for the given extension or None.

kinds() → tuple[str, ...]

Return all registered kinds in registration order.

__contains__(kind: object) → bool

Return True when the given value is a registered asset kind.

Manager

Coordinate static backends, asset discovery, and placeholder injection.

The static manager loads backends lazily on first use, owns the shared asset discovery instance, caches page-tree roots, and replaces every registered placeholder token with the rendered tags once rendering completes. It also injects the next.min.js wiring unless the injection policy is DISABLED.

The module-level default_manager is a lazy handle around a single static manager instance. Test code may replace the wrapped instance by assigning to default_manager._wrapped without mucking with module-level state. The settings-change hook in next.conf resets the wrapper when NEXT_FRAMEWORK changes.

class next.static.manager.StaticManager

Coordinate static backends, asset discovery, and placeholder injection.

Backends are loaded lazily from NEXT_FRAMEWORK[‘DEFAULT_STATIC_BACKENDS’] on first access. URL resolution is handled by the built-in staticfiles backend by default, which delegates to Django staticfiles.

__init__() → None

Initialise empty backend and discovery caches, loaded lazily.

__len__() → int

Return the number of configured backends, loading them if needed.

property default_backend: StaticBackend

Return the first configured backend used for file registration.

property discovery: AssetDiscovery

Return the shared asset discovery instance.

discover_page_assets(file_path: Path, collector: StaticCollector) → None

Forward page asset discovery to the shared discovery instance.

discover_component_assets(info: ComponentInfo, collector: StaticCollector) → None

Forward component asset discovery to the shared discovery instance.

inject(html: str, collector: StaticCollector, *, page_path: Path | None = None, request: HttpRequest | None = None) → str

Replace every registered placeholder token with rendered tags.

Each slot in default_placeholders contributes its bucket of collected assets. Asset rendering dispatches through the backend method named by KindRegistry.renderer(asset.kind), so adding new kinds with new renderer methods does not require any changes here. The scripts slot also receives the next-dj runtime wiring when the injection policy is AUTO.

A missing placeholder is left unchanged because str.replace returns the original string when there is nothing to replace. An empty collector yields empty tag sections. The preload hint is injected before </head> under the same policy.

The optional request argument is forwarded to backend tag renderers and to the collector_finalized and html_injected signals. Backends may use it to rewrite asset URLs based on per-request state. The default backend ignores it.

create_collector() → StaticCollector

Build a new StaticCollector wired with configured strategies.

page_roots() → tuple[Path, ...]

Return absolute page-tree roots from configured page backends.

class next.static.manager.DefaultStaticManager

Lazy handle that defers the construction of a static manager.

The wrapped manager is built on first access. Tests may replace it by assigning to _wrapped directly. The settings-change hook in next.conf resets the wrapper when NEXT_FRAMEWORK changes.

next.static.manager.reset_default_manager() → None

Drop the wrapped static manager so the next access rebuilds it.

Hooked into the settings_reloaded signal from next.conf so that test code changing NEXT_FRAMEWORK via override_settings sees a fresh manager on the next access.

default_manager is the process-wide static manager handle exported from next.static. It builds its wrapped StaticManager lazily on first access. reset_default_manager drops that wrapped instance so the next access rebuilds it, which keeps the manager consistent when NEXT_FRAMEWORK changes under override_settings. The DefaultStaticManager wrapper class itself is internal and is not part of the public API.

Scripts

See JavaScript Context for the runtime script options and the NEXT_JS_OPTIONS keys.

Pluggable builder for the next.min.js preload, script, and init tags.

The builder produces the three HTML fragments that wire window.Next into the rendered page. The first fragment is a preload hint injected before </head> so the browser starts downloading during HTML parsing. The second fragment is a blocking script tag for the compiled runtime. The third fragment is an inline script that feeds the serialized JS context into Next._init.

Every template is an instance attribute, so users can override any single tag without subclassing. An injection policy controls whether the static manager emits those tags at all.

class next.static.scripts.ScriptInjectionPolicy(*values)

Controls whether next.min.js is automatically injected.

The AUTO value is the default. Under AUTO the static manager emits the preload hint, the <script> tag, and the Next._init call into every rendered page. The DISABLED value skips injection entirely and is useful when a page does not need window.Next, for example a raw API response rendered through the page machinery. The MANUAL value skips automatic injection but still builds the fragments on request so users can emit the tags themselves from a template.

AUTO = 'auto'

DISABLED = 'disabled'

MANUAL = 'manual'

class next.static.scripts.NextScriptBuilder(next_js_url: str, *, preload_template: str | None = None, script_tag_template: str | None = None, init_template: str | None = None, policy: ScriptInjectionPolicy = ScriptInjectionPolicy.AUTO)

Builds the preload hint, script tag, and init script for window.Next.

The next_js_url argument is the public URL of the compiled next.min.js asset. The optional preload_template, script_tag_template, and init_template arguments override the defaults. The preload and script templates must contain the {url} placeholder. The init template must contain the {payload} placeholder, which receives the JSON-serialized JS context. The policy argument is consulted by the static manager before injection and defaults to ScriptInjectionPolicy.AUTO.

DEFAULT_PRELOAD: ClassVar[str] = '<link rel="preload" as="script" href="{url}">'

DEFAULT_SCRIPT_TAG: ClassVar[str] = '<script src="{url}"></script>'

DEFAULT_INIT: ClassVar[str] = '<script>Next._init({payload});</script>'

__init__(next_js_url: str, *, preload_template: str | None = None, script_tag_template: str | None = None, init_template: str | None = None, policy: ScriptInjectionPolicy = ScriptInjectionPolicy.AUTO) → None

Store the URL, tag templates, and injection policy.

property policy: ScriptInjectionPolicy

Return the configured script injection policy.

property url: str

Return the resolved next.min.js URL.

preload_link() → str

Return the preload hint tag for early browser download.

script_tag() → str

Return the blocking script tag that executes next.min.js.

init_script(js_context: Mapping[str, Any], *, key_serializers: Mapping[str, JsContextSerializer] | None = None) → str

Return the inline script that passes the context to Next._init.

Delegates serialisation to the configured JsContextSerializer so the init payload honours the same encoding rules as values registered through StaticCollector.add_js_context. When key_serializers is supplied, each top-level key listed there is encoded with its dedicated serializer and the rest fall back to the global default.

classmethod from_options(next_js_url: str, options: Mapping[str, Any] | None = None) → NextScriptBuilder

Build a script builder from an options mapping.

The recognised keys are preload_template, script_tag_template, init_template, and policy. The policy value may be a ScriptInjectionPolicy member or the string value of one of its members. Any other value raises ValueError.

JS Context Serializer

Pluggable JS-context serializers for @context(serialize=True) values.

StaticCollector.add_js_context delegates value encoding to a JsContextSerializer. The default implementation uses DjangoJSONEncoder, which handles the same set of types that the framework has always accepted. Applications that want to serialise pydantic models, msgspec structs, or any other type can point the JS_CONTEXT_SERIALIZER option at a class that implements the protocol.

class next.static.serializers.JsContextSerializer(*args, **kwargs)

Encode values destined for window.Next.context.

Implementations turn Python values into JSON text. The contract is deliberately narrow so that custom types can travel to the client without bolt-on Django encoder extensions.

dumps(value: Any) → str

Return a JSON string for value.

__init__(*args, **kwargs)

class next.static.serializers.JsonJsContextSerializer

Serialise values with Django’s DjangoJSONEncoder.

This is the process-wide default. It mirrors the behaviour built into the collector before serializers became pluggable. The output uses compact separators so the inline init payload stays small.

dumps(value: Any) → str

Return a compact JSON string produced by json.dumps.

class next.static.serializers.PydanticJsContextSerializer

Serialise values through pydantic model dump when available.

Unknown types fall through to DjangoJSONEncoder, so lists and dicts containing mixed pydantic and plain values still serialise without a second code path.

__init__() → None

Import pydantic lazily so tests without it keep working.

dumps(value: Any) → str

Return a compact JSON string with pydantic models unwrapped.

next.static.serializers.resolve_serializer() → JsContextSerializer

Return the configured serializer or the process-wide default.

The resolver reads NEXT_FRAMEWORK[“JS_CONTEXT_SERIALIZER”] on every call. Returning a fresh instance each time keeps the hot path free of caching edge cases during test overrides.

Defaults

Bootstrap registrations for the built-in css, js, and module asset kinds.

The static subsystem is type-agnostic. The built-in kinds are not privileged in core code, they are registered through the same public API that user projects use to teach the framework about additional file types like jsx or wasm.

register_defaults is called from the framework AppConfig.ready so the defaults are in place before any request lands. Idempotent re-registration with identical parameters is allowed and lets test suites that swap settings during a session keep using the public API.

next.static.defaults.register_defaults() → None

Register the built-in placeholder slots and asset kinds.

Staticfiles Finder

Django staticfiles finder that exposes next-dj co-located assets.

The finder surfaces every template.css, layout.js, and component.css plus any stems registered on the stem registry under the next/ staticfiles namespace. The usual {% static “next/about.css” %} call works without the user configuring anything.

The logical-path and source-file mapping is computed by the co-located asset discovery helper below, which shares the same PathResolver used at request-time discovery. The two layers agree on every URL.

next.static.finders.discover_colocated_static_assets() → dict[str, Path]

Map staticfiles logical paths to absolute source files on disk.

The helper scans every configured page-backend tree plus registered components. It honors the process-wide stem and kind registries, so custom stems registered during AppConfig.ready are picked up.

class next.static.finders.NextStaticFilesFinder

Expose next-dj co-located assets under the next/ staticfiles namespace.

__init__() → None

Initialise an empty mapping and storage, populated lazily on first lookup.

find(path: str, find_all: Literal[False] = False) → str | None

find(path: str, find_all: Literal[True]) → list[str]

Resolve the logical path to an absolute filesystem path or list.

list(ignore_patterns: Iterable[str] | None) → Iterator[tuple[str, Storage]]

Yield logical-path and storage pairs for collectstatic.

NextStaticFilesFinder is the Django staticfiles finder for co-located assets. It maps assets such as template.css, layout.js, component.css, and any registered stems to their source files under the next/ staticfiles namespace. It surfaces every such asset to collectstatic for production output and to {% static "next/..." %} lookups when DEBUG is true and the staticfiles app serves files itself. The mapping is rebuilt on each lookup so assets added at runtime are picked up.

The finder is appended to STATICFILES_FINDERS automatically by NextFrameworkConfig.ready through next.apps.staticfiles.install. The install step is idempotent and skips the entry when it is already present. You do not need to list it in STATICFILES_FINDERS yourself. The dotted path is next.static.NextStaticFilesFinder. You can confirm it is active by running manage.py findstatic next/some-component/component.css.

Signals

See Signals Reference and Static Signals for the static signals (asset_registered, collector_finalized, html_injected, backend_loaded).

See Also

See also

Static Assets for the topic subtree. Static Pipeline for the internal flow. Static Files in Production for production collectstatic configuration and the finder setup.