Server Reference

Module Summary

next.server exposes the autoreload watcher, the watch-spec helpers, and the filesystem roots used by the development server. The Django wiring that activates them lives in next.apps (see Apps Reference).

Public API

Autoreload

NextStatReloader subclasses Django’s StatReloader. In addition to watching .py mtimes, it recomputes the discovered route set on every tick and triggers a reload when pages appear or disappear from the routing tree, even when no file mtime changed. .djx templates are not watched. They are re-read on render with mtime-based invalidation.

Custom StatReloader that also watches the discovered route set.

NextStatReloader subclasses Django’s StatReloader and adds a route set comparison between ticks. When pages appear or disappear from the routing tree, the reloader notifies Django even if no mtime changed. .djx templates are deliberately not watched. They are re-read on render with mtime-based invalidation inside pages and components.

class next.server.autoreload.NextStatReloader

Reload on route set changes in addition to .py mtime changes.

__init__() → None

Initialise the cached route set used for tick-to-tick diffs.

tick() → Generator[None, None, None]

Recompute routes, compare to the previous tick, then delegate.

Watcher

register_autoreload_watch_spec(path, glob) registers one extra directory and glob pair with the watcher. Call it from your own AppConfig.ready to have additional trees watched without changing the next package. The built-in specs for pages and filesystem components are derived from NEXT_FRAMEWORK and need no registration.

iter_all_autoreload_watch_specs returns the deduplicated list of built-in watch specs together with every pair registered through register_autoreload_watch_spec. Each entry is a (path, glob) tuple consumed by StatReloader.watch_dir. The function emits the watch_specs_ready signal on every call so subscribers can inspect the resolved set.

FilesystemWatchContributor is a runtime-checkable protocol declaring a single iter_watch_specs() method. It is exported for type annotations only. The watcher does not iterate contributors at runtime, so registration goes through register_autoreload_watch_spec.

Watch-spec helpers for the development file reloader.

FilesystemWatchContributor is a Protocol for objects that contribute (path, glob) pairs to Django’s StatReloader.watch_dir. The module exposes built-in defaults derived from NEXT_FRAMEWORK and a registry for extra pairs contributed by third-party apps.

class next.server.watcher.FilesystemWatchContributor(*args, **kwargs)

Yield (root, glob) pairs for StatReloader.watch_dir.

Each tuple is a filesystem root and a glob pattern relative to that root.

iter_watch_specs() → Iterable[tuple[Path, str]]

Yield (root, glob) pairs for StatReloader.watch_dir.

__init__(*args, **kwargs)

next.server.watcher.register_autoreload_watch_spec(path: Path, glob: str) → None

Register one extra directory and glob pair for the file watcher.

Built-in globs already come from NEXT_FRAMEWORK. Call this from your own AppConfig.ready if you need more trees watched without changing the next package.

next.server.watcher.iter_all_autoreload_watch_specs() → list[tuple[Path, str]]

Return default watch specs plus registered extras, deduplicated.

Roots

get_framework_filesystem_roots_for_linking returns the sorted unique roots derived from page trees and component DIRS. Each root is resolved to an absolute path. Tooling that needs to symlink or scan those directories reads them from here instead of recomputing paths.

Filesystem-root helpers for build tooling and symlink management.

These helpers are distinct from watch specs. They return a canonical list of directories that downstream tooling (dockerfiles, editors, symlink builders) needs, without reloader semantics.

next.server.roots.get_framework_filesystem_roots_for_linking() → list[Path]

Return sorted unique roots from page trees and component DIRS.

Signals

watch_specs_ready fires after the reloader resolves the full watch-spec list. The sender is the iter_all_autoreload_watch_specs function. The single payload argument is specs, the deduplicated (path, glob) list passed to the watcher.

See Signals Reference for the signal index.

See Also

See also

Autoreload for the reloader internals.