Extend a default backend entry

Problem

You want to override one key of a default backend entry, such as PAGES_DIR or a value inside OPTIONS, without copying the whole framework default into your settings.

Solution

Use next.conf.extend_default_backend. The helper returns a deep copy of the default backend list with one entry patched by your overrides. It raises ImproperlyConfigured for an unknown setting name and IndexError for an out of range index. Both failures surface at Django startup, not at request time.

Walkthrough

Pick the backend list.

Setting key	Used by
PAGE_BACKENDS	File router and layout chain.
COMPONENT_BACKENDS	Component discovery and rendering.
STATIC_BACKENDS	Static collector and asset rendering.
FORM_ACTION_BACKENDS	Form action dispatch.
PARTIAL_BACKENDS	Partial rendering protocol and patch wire format.

The helper supports these five backend list settings.

Call the helper with the setting name and the keys to override.

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 the default PAGE_BACKENDS list with the first entry PAGES_DIR set to routes and every other key kept.

Override a nested OPTIONS key

Nested dicts such as OPTIONS are merged, not replaced. Adjacent keys survive.

config/settings.py

from next.conf import extend_default_backend

NEXT_FRAMEWORK = {
    "PAGE_BACKENDS": extend_default_backend(
        "PAGE_BACKENDS",
        OPTIONS={"context_processors": ["notes.context_processors.tenant"]},
    )
}

Patch a specific entry

The index keyword selects which entry of the default list to patch. The default is 0, the first entry.

config/settings.py

extend_default_backend("PAGE_BACKENDS", index=0, APP_DIRS=False)

When to write the list by hand

extend_default_backend patches an existing default entry. It does not add a new backend. To register a custom backend, write the full list yourself.

config/settings.py

NEXT_FRAMEWORK = {
    "FORM_ACTION_BACKENDS": [
        {"BACKEND": "notes.backends.AuditedFormActionBackend"},
    ]
}

A custom backend usually subclasses the default, so it already inherits every default behaviour. See Write a form action backend.

Verification

Print the resolved setting from a Django shell.

shell

uv run python manage.py shell -c "
from next.conf import next_framework_settings
print(next_framework_settings.PAGE_BACKENDS)
"

The list shows the default entry with your overrides applied.

See also

See also

Extending for the broader picture. Configuration reference for the public API.