Settings

Module summary

This page lists every key inside NEXT_FRAMEWORK with its framework default and a short description. Set NEXT_FRAMEWORK in settings.py to override any of these values.

For production-specific recommendations (which values to change and why), see Production settings.

Key naming

Keys inside NEXT_FRAMEWORK carry no DEFAULT_ prefix. The dict itself is the framework defaults namespace. A plural *_BACKENDS key holds an ordered list of sources the manager consults in order. PARTIAL_BACKENDS is the exception. Partial rendering uses a single protocol backend, so only the first entry runs. A singular *_BACKEND key holds the one engine for a concern. A subsystem prefix (PAGE_, COMPONENT_, STATIC_, FORM_, URL_, TEMPLATE_, JS_, PARTIAL_) groups related keys. NEXT_JS_OPTIONS stands outside the prefix scheme and configures the bundled client runtime.

Backends

PAGE_BACKENDS

List of page backend configurations.

Default value.

[
    {
        "BACKEND": "next.urls.FileRouterBackend",
        "DIRS": [],
        "APP_DIRS": True,
        "PAGES_DIR": "pages",
        "OPTIONS": {"context_processors": []},
    }
]

Each entry is passed to the backend constructor. Keys are BACKEND, DIRS, APP_DIRS, PAGES_DIR, and OPTIONS.

DIRS accepts two kinds of entry. An absolute or project-relative path that resolves to an existing directory is added as an extra page root. A plain string that does not resolve to a directory is treated as a skip name. The router will not enter any directory with that name during the file walk.

See File router for the full semantics including examples.

COMPONENT_BACKENDS

List of component backend configurations.

Default value.

[
    {
        "BACKEND": "next.components.FileComponentsBackend",
        "DIRS": [],
        "COMPONENTS_DIR": "_components",
    }
]

STATIC_BACKENDS

List of static backend configurations.

Default value.

[
    {
        "BACKEND": "next.static.StaticFilesBackend",
        "OPTIONS": {},
    }
]

The first static backend’s OPTIONS dict accepts JS_CONTEXT_POLICY, a dotted path to a conflict-resolution class. The static manager applies the policy when two context functions publish the same key for serialisation. See JavaScript context under Key conflict policy for the available policies and an example.

The same OPTIONS dict accepts DEDUP_STRATEGY, a dotted path to a dedup strategy class the collector instantiates once per request to drop assets several components register more than once. See Deduplication for the bundled strategies and the custom-strategy protocol.

FORM_ACTION_BACKENDS

List of form action backend configurations.

Default value.

[
    {
        "BACKEND": "next.forms.RegistryFormActionBackend",
        "OPTIONS": {},
    }
]

FORM_AUTODISCOVER

Boolean that controls whether NextFrameworkConfig.ready imports the forms submodule of every installed app on startup.

Default value True.

When True, shared forms declared in app/forms.py register before the first request arrives. Set to False to disable the automatic import and manage registration manually.

FORM_ANCHOR_FILES

List of file basenames that receive page scope during auto-registration. A form class declared in a file whose basename appears in this list is keyed to the absolute path of that file. All other files produce shared scope.

Default value None, which uses the built-in set ["page.py", "component.py"]. Set to a list of strings to replace the default set. The configured list is used as is, so include "page.py" and "component.py" explicitly when they should stay anchors.

FORM_WIZARD_BACKEND

Single form wizard backend configuration. The backend persists a wizard’s per-step draft data between requests.

Default value.

{
    "BACKEND": "next.forms.SessionFormWizardBackend",
    "OPTIONS": {},
}

The bundled SessionFormWizardBackend stores each step’s cleaned data in the Django session through a typed value codec, so drafts share the durability of the session engine. It reads no OPTIONS keys. The bundled CacheFormWizardBackend stores drafts in the Django cache instead. It reads two keys from OPTIONS. CACHE_ALIAS names the cache to use, defaulting to "default", and TIMEOUT sets the draft expiry in seconds, defaulting to SESSION_COOKIE_AGE. Set BACKEND to a dotted path that subclasses FormWizardBackend to swap the persistence layer. See Wizard backend for the contract, the codec, and a custom backend.

PARTIAL_BACKENDS

List of partial protocol backend configurations. The first entry is active and owns the patch wire format that partial rendering serialises over HTTP and Server-Sent Events. Entries after the first are ignored, and manage.py check reports them with next.W071. The value has to be a list, since any other shape is dropped in favour of the default and manage.py check reports it with next.E067.

Default value.

[
    {
        "BACKEND": "next.partial.PartialProtocolBackend",
        "OPTIONS": {
            "VERSION": "manifest",
            "PUSH_WIZARD_STEPS": False,
            "SSE": {
                "HEARTBEAT_SECONDS": 25,
                "RETRY_MS": 3000,
            },
        },
    },
]

The OPTIONS keys tune the active backend. VERSION is the source of the X-Next-Version stamp. The sentinel "manifest" hashes the staticfiles manifest when the active storage hashes its files, and an explicit string pins the version yourself. Without a manifest storage the version guard stays silent at runtime, and manage.py check reports next.W069. PUSH_WIZARD_STEPS is the global default for pushing wizard steps to browser history, which a wizard’s Meta.push_steps overrides per wizard. SSE.HEARTBEAT_SECONDS is the keepalive period in seconds for an async stream source, and SSE.RETRY_MS is the EventSource reconnect hint in milliseconds sent in the leading stream frame.

See Partial rendering reference for the wire protocol and SSE under WSGI and ASGI for the stream contract.

Routing

URL_NAME_TEMPLATE

Template used to compute URL names from directory paths.

Default value "page_{name}".

The framework normalises the path through the parser and substitutes {name} with the result. Slashes, square brackets, colons, hyphens, and underscores are collapsed to a single underscore, and the leading and trailing underscores are stripped. The directory path notes/[id] becomes notes_id and produces the URL name page_notes_id.

URL_RESOLVER

Dotted path to the resolver class that wraps the framework urlpatterns.

Default value "next.urls.TrieURLResolver".

The class is instantiated with a root route pattern and the lazy sequence of router and form-action patterns, so it owns every resolution under the include("next.urls") mount. The default TrieURLResolver resolves a static route through a dictionary lookup and a parameterised route through a walk over a segment trie, with the final match delegated to standard Django pattern resolution. Set the key to "django.urls.resolvers.URLResolver" to opt out of the trie and run every resolution through Django’s plain linear scan. A custom value must name a URLResolver subclass whose constructor accepts the same pattern and pattern-sequence pair. A path that fails to import, or one that names anything other than a URLResolver subclass, raises ImproperlyConfigured at startup. The resolver is rebuilt on settings reload, so override_settings swaps it without a restart.

See URL router for the resolution algorithm.

Templates

TEMPLATE_LOADERS

List of template loader dotted paths.

Default value.

["next.pages.loaders.DjxTemplateLoader"]

Loaders are consulted in order, first match wins.

JavaScript context

NEXT_JS_OPTIONS

Dict passed to NextScriptBuilder.from_options for the bundled next.min.js runtime. Keys are the injection policy (auto, disabled, or manual) and the optional string templates preload_template, script_tag_template, and init_template.

Default value {} (automatic injection with default templates).

Serialisation of window.Next.context is controlled by JS_CONTEXT_SERIALIZER and by @context(..., serialize=True), not by this dict.

See JavaScript context under Runtime script options for the full table and examples.

JS_CONTEXT_SERIALIZER

Dotted path to a class that implements the JsContextSerializer protocol. The class is instantiated with no arguments and its dumps method encodes every value bound for window.Next.context.

Default value None, which selects the built-in JsonJsContextSerializer.

resolve_serializer reads this setting on every call, so override_settings takes effect without a restart. A value that does not resolve to a usable serializer triggers the next.W042 warning during manage.py check. At render time such a value raises ImportError or TypeError on first use, so fix the dotted path rather than rely on a fallback. The built-in JsonJsContextSerializer steps in only when the setting is unset.

See Static reference under JS context serializer for the protocol and the bundled serializers.

Strictness

STRICT_CONTEXT

When True, any TypeError, ValueError, AttributeError, or KeyError raised by a Django context processor is re-raised immediately. The default behaviour is to log a warning and swallow the exception. The check applies only to processors listed under a page backend OPTIONS["context_processors"]. Context callables registered with @context always propagate their exceptions regardless of this setting. When False, the default, a failing processor is skipped so local development keeps rendering.

Default value False. Production settings explains when to turn this on in production.

STRICT_LOADING

When True, a broken body source fails the request instead of degrading silently. A page.py that raised while importing re-raises the recorded PageModuleImportError on every request to that page. A {% component %} name that does not resolve raises TemplateSyntaxError with a did-you-mean hint. When False, the default, the framework logs and keeps rendering. A broken page.py answers 404 while logger.exception records the full traceback, and a missed component renders as an empty string with a warning log. settings.DEBUG raises the same page-load error without this flag, so the flag matters for a DEBUG=False deployment. In every mode the failure is scoped to the broken page, sibling pages keep serving.

Default value False. See Pages reference for the page-load contract, Template tags for the component-miss outcomes, and Production settings for the production recommendation.

Loudness axes

Five independent switches decide how loudly a broken piece fails.

Axis	Covers	When loud
settings.DEBUG	Django development mode as a whole	A broken page.py raises with the standard technical 500 page, and a component miss renders a visible HTML comment.
STRICT_LOADING	page.py import failures and {% component %} misses	Raises regardless of DEBUG.
STRICT_CONTEXT	Django context processor exceptions	Raises regardless of DEBUG.
next.E076	Eight NEXT_FRAMEWORK keys whose mistyped value the settings merge silently drops	Always, on manage.py check.
next.E077	A NEXT_FRAMEWORK that is not a dict at all, which the settings layer ignores entirely	Always, on manage.py check.
next.W072	The four NEXT_FRAMEWORK bool keys, where bool() coercion can invert the intent	Always, on manage.py check, as a warning rather than an error.

DEBUG=True turned on temporarily, for serving static files or profiling, also changes the error semantics of pages. A broken page.py that answered 404 starts raising, so the switch flips more than the error page and the toolbar. The configuration checks stay independent of every flag above, so manage.py check reports next.E076, next.E077, and next.W072 in any combination of DEBUG and the strict flags. See System checks for each check condition.

LAZY_COMPONENT_MODULES

Controls bulk import of component.py modules in configured component roots during next.apps.components.install. When True, each component.py is imported on demand the first time get_component resolves it. Components discovered through _components directories beside page files are imported by the file router as it walks the page tree, regardless of this flag.

Default value False. See Production settings for production defaults and Testing for the eager_load_components helper.

Patching defaults

Use next.conf.extend_default_backend to patch one key of a default backend entry without copying the whole default.

config/settings.py

from next.conf import extend_default_backend

NEXT_FRAMEWORK = {
    "PAGE_BACKENDS": extend_default_backend(
        "PAGE_BACKENDS",
        PAGES_DIR="routes",
    )
}

The helper returns a deep copy of the default list with the entry at index (default 0) patched by the keyword overrides. Nested dicts such as OPTIONS are merged.

The helper accepts five backend-list keys.

• PAGE_BACKENDS

• COMPONENT_BACKENDS

• STATIC_BACKENDS

• FORM_ACTION_BACKENDS

• PARTIAL_BACKENDS

The helper raises ImproperlyConfigured when key is not one of these settings. It raises IndexError when index is out of range for the default list.

See Configuration reference for the helper API and Extend a default backend entry for the recipe.

See also

See also

Extending for the broader picture. Production settings for production tuned values. JavaScript context for NEXT_JS_OPTIONS. next.static.scripts.ScriptInjectionPolicy for the policy enum.