How-to guides#

How-to guides answer task-shaped questions. Each recipe states a problem, gives one minimal solution, walks through the steps, and shows how to verify the result. Topic guides cover the underlying concepts, see Topic guides.

Pages and routing

Add a page: Add a new page to a running project.
Reverse URLs: Build URLs from page templates and Python.
Reload routes from code: Trigger router reload at runtime.
Write a router backend: Implement a router backend that reads URLs from a database.
Read query parameters: Read query-string values with the DQuery marker.
Add a custom template loader: Plug an extra TemplateLoader into TEMPLATE_LOADERS.
Require login on file-routed pages: Gate routed pages behind authentication.
Internationalize routes: Serve the page tree under per-language URL prefixes.
Customize 404 and 500 pages: Replace the default 404 and 500 pages.

Context and components

Share context across pages: Publish values once for an entire page tree.
Resolve feature flags with DI: Resolve feature flags through a custom dependency provider.
Build a composite component: Build a component that takes content through slots.
Share components across projects: Reuse a UI kit across several page roots.

Static assets

Add a new asset kind: Recognise a new file extension during static collection.
Add a custom stem: Treat additional filenames as component assets.
Customise rendered static tags: Customise the rendered link and script tags.
Override the JS context serializer: Replace the default JSON serializer for the Next object.
Resolve asset URLs through a custom backend: Add a custom asset kind with its own renderer.

Forms

Handle file uploads: Accept file inputs in a form action.
Use ModelForm for CRUD: Power create, update, and delete pages with ModelForm.
Enforce object-level permissions: Gate a ModelForm edit on the loaded row’s owner.
Use formsets: Render and validate a Django formset.
Build a multi-step wizard: Gather data across several steps and finalise one row at the end.
Move from django-formtools: Port a formtools WizardView flow to FormWizard.
Style forms with crispy-forms and widget-tweaks: Render forms through crispy-forms and widget-tweaks inside {% form %}.
Drive form actions with htmx: Submit forms over htmx and swap only the form region.
Integrate django-allauth forms: Drive the allauth login, signup, and reset forms through form actions.
Write a form action backend: Plug a new validation pipeline into the dispatcher.
Extend a default backend entry: Patch one key of a default backend entry through extend_default_backend.

Testing

Test a page with actions: Test a page that posts to a registered action.
Test a component in isolation: Render and assert on one component without a page.

Integration and operations

Integrate Django admin: Run Django admin alongside next.dj pages.
Scope requests per tenant: Scope every request to one tenant across the stack.
Observe framework signals: Receive framework signals in production receivers.
Stream live updates with SSE: Push live updates to the browser with server-sent events.
Split settings per environment: Split settings into base, dev, and prod modules.