Configuration Reference

Module Summary

next.conf merges user NEXT_FRAMEWORK settings with framework defaults. It exposes the merged-settings object, the import helpers, the extend_default_backend helper, and the settings_reloaded signal.

Public API

Settings Class

Merged view of settings.NEXT_FRAMEWORK with framework defaults.

The NextFrameworkSettings class reads the user mapping lazily and merges it with DEFAULTS on first access. Merge results are cached until reload() drops the cache and emits settings_reloaded. Package managers that depend on the merged values subscribe to that signal and reset their own state.

class next.conf.settings.NextFrameworkSettings

Lazy merged view of top-level keys declared in DEFAULTS.

DEFAULTS: ClassVar[dict[str, Any]] = {'DEFAULT_COMPONENT_BACKENDS': [{'BACKEND': 'next.components.FileComponentsBackend', 'COMPONENTS_DIR': '_components', 'DIRS': []}], 'DEFAULT_FORM_ACTION_BACKENDS': [{'BACKEND': 'next.forms.RegistryFormActionBackend', 'OPTIONS': {}}], 'DEFAULT_PAGE_BACKENDS': [{'APP_DIRS': True, 'BACKEND': 'next.urls.FileRouterBackend', 'DIRS': [], 'OPTIONS': {'context_processors': []}, 'PAGES_DIR': 'pages'}], 'DEFAULT_STATIC_BACKENDS': [{'BACKEND': 'next.static.StaticFilesBackend', 'OPTIONS': {}}], 'JS_CONTEXT_SERIALIZER': None, 'LAZY_COMPONENT_MODULES': False, 'NEXT_JS_OPTIONS': {}, 'STRICT_CONTEXT': False, 'TEMPLATE_LOADERS': ['next.pages.loaders.DjxTemplateLoader'], 'URL_NAME_TEMPLATE': 'page_{name}'}

IMPORT_STRINGS: ClassVar[frozenset[str]] = frozenset({})

__init__() → None

Initialise empty merge and attribute caches.

reload() → None

Drop merge and import caches and emit the reload signal.

Package-level managers listen to settings_reloaded and reset their own state. This method only clears caches owned by the settings object itself.

__getattr__(attr: str) → Any

Return merged values for keys declared in DEFAULTS.

__setattr__(name: str, value: Any) → None

Allow only internal cache attributes and raise for declared keys.

Defaults

Framework-level defaults for the settings.NEXT_FRAMEWORK mapping.

The values stored here are deep-copied into the merged view on every reload. Nothing in this module imports from the rest of the framework, which keeps the configuration layer at the bottom of the dependency graph.

Helpers

Helpers for writing compact NEXT_FRAMEWORK settings blocks.

next.conf.helpers.extend_default_backend(key: str, *, index: int = 0, **overrides: Any) → list[dict[str, Any]]

Return a NEXT_FRAMEWORK[key] list with one backend entry patched.

The returned list is a deep copy of the default entries with the entry at index updated by overrides. Nested dicts such as OPTIONS are merged instead of replaced so partial overrides do not drop adjacent keys.

Raises ImproperlyConfigured when key is not a known backend-list setting. Raises IndexError when index is out of range for the default list.

Import Utilities

next.conf.imports.import_class_cached(dotted_path: str) → type[Any]

Import a class by dotted path and cache it until the cache is cleared.

next.conf.imports.perform_import(val: Any, setting_name: str) → Any

Resolve a dotted import path through the cache when the value is a string.

next.conf.imports.clear_import_cache() → None

Drop every cached dotted-path import.

next.conf.imports.IMPORT_STRINGS: frozenset[str] = frozenset({})

frozenset() -> empty frozenset object frozenset(iterable) -> frozenset object

Build an immutable unordered collection of unique elements.

Signals

See Signals Reference for the settings_reloaded signal.

See Also

See also

Settings for the full NEXT_FRAMEWORK key catalog. Extending for the helper patterns.