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.

Backends

DEFAULT_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.

DEFAULT_COMPONENT_BACKENDS

List of component backend configurations.

Default value.

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

DEFAULT_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.

DEFAULT_FORM_ACTION_BACKENDS

List of form action backend configurations.

Default value.

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

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.

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 and the framework falls back to JsonJsContextSerializer.

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.

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 = {
    "DEFAULT_PAGE_BACKENDS": extend_default_backend(
        "DEFAULT_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 raises ImproperlyConfigured when key is not a known backend-list setting. 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.