Static Files & Front-End Assets

The listings belong to the catalog app of the running Bookshelf scenario. The pieces are: catalog/static/catalog/ (css/site.css, js/app.js, img/logo.svg, plus the date-picker files), a project-level static/site-wide.css, templates catalog/base.html, book_form.html and spa.html, widgets.py, forms.py, storage.py, a vite template-tag library, a frontend/ folder holding a Vite project, and catalog/tests.py. The general layout of a project is on Project Structure & Apps and the full settings story on Settings & Configuration; this page shows only the static-related settings.

A finder maps a relative path such as catalog/css/site.css to a file on disk. The two default finders are FileSystemFinder (the directories in STATICFILES_DIRS) and AppDirectoriesFinder (the static/ folder of every installed app, in INSTALLED_APPS order). STATICFILES_FINDERS can add the others or reorder them. The first match wins, which is why app files go in a folder named after the app: catalog/static/catalog/css/site.css is addressed as catalog/css/site.css, and a second app can ship its own css/site.css without a collision. A STATICFILES_DIRS entry may also be a (prefix, path) pair, which exposes a folder under a URL sub-path; the Vite section uses that.

Source: Django: findstatic

findstatic is the debugging aid: it shows which file a path resolves to and the exact search order, which is the first thing to check when the wrong version of a file is served. From code, finders.find() returns the same answer and finders.searched_locations lists where it looked. Since 6.1 the find_all argument of find() replaced all (deprecated in 5.2, removed in 6.1), so old code that passes all=True fails on 6.1.

Templates must never contain a literal /static/…​ URL. The static tag asks the staticfiles storage for the URL, so changing STATIC_URL, moving to a CDN or turning on hashed names needs no template edits.

Source: Django: static template tag

Three details matter. The tag lives in the static library, loaded in every template that uses it (the old staticfiles and admin_static libraries were removed in 3.0). It works with any storage, because it simply calls .url() on the staticfiles storage. And {% static 'x' as url %} stores the URL in a variable, handy for inline CSS or JSON. get_static_prefix and get_media_prefix return only the prefix, and the static() context processor adds STATIC_URL to every RequestContext. The template language itself is on Templates.

The tests that pin these behaviours are short.

Source: Django: Finders module

The test client does not serve static files. A browser-driven test (Selenium or Playwright, see pytest, Factories & Browser Tests and End-to-End Testing with Real Browsers) does, and LiveServerTestCase only knows files already collected under STATIC_ROOT. StaticLiveServerTestCase serves through the finders instead, as runserver does.

Source: Django: StaticLiveServerTestCase and Testing static files

The storage needs a manifest, and the test runner does not run collectstatic, so the official advice is to keep the default StaticFilesStorage in tests. A test that wants to prove the hashing builds its own output directory:

Source: Django: Overriding settings and ManifestStaticFilesStorage.manifest_strict

The ValueError is the failure you will meet in production: a template references a file that is missing from the manifest, usually because collectstatic was not run after adding it. That makes it a feature, not a bug: the error shows up on the first request instead of as a silent 404 in the browser. manifest_strict = False in a subclass relaxes it, but not as far as the documentation’s wording suggests: in the scratch run a file that exists in storage but is missing from the manifest got its hashed name computed on the fly (a hash read per request), and a file that does not exist at all still raised ValueError.

Source: ManifestStaticFilesStorage.manifest_strict

The class exposes a few hooks, all by subclassing. manifest_storage (4.0) moves staticfiles.json somewhere other than STATIC_ROOT; max_post_process_passes (default 5) bounds the number of rewriting passes for files that reference each other; support_js_module_import_aggregation (experimental, 4.2) also rewrites JavaScript import and export …​ from paths; file_hash() replaces the hash function; file_permissions_mode and directory_permissions_mode change the permissions of collected files (they default to FILE_UPLOAD_PERMISSIONS and FILE_UPLOAD_DIRECTORY_PERMISSIONS).

Source: Django: ManifestStaticFilesStorage

A test with STORAGES["staticfiles"]["BACKEND"] = "catalog.storage.SiteManifestStorage" confirmed that collectstatic wrote staticfiles.json to BASE_DIR and nothing to STATIC_ROOT. Two cautions from the reference: a file’s integrity attribute (Subresource Integrity) must be computed on the file as served, and Django has no out-of-the-box tool for that; and manifest_hash, a single hash that changes whenever any file in the manifest changes (4.2), is meant for single-page applications that want to detect a new deployment, as the Pairing Django with React, Vue or Angular section shows.

WhiteNoise is a community package (not part of Django) that serves the collected files from inside the application, with correct Cache-Control headers, gzip and optional Brotli versions, and ETag support. It is a good fit for containers and platform-as-a-service hosting, and it is also what most small deployments need. Installation is a package (pip install whitenoise; add the brotli extra for Brotli) and two settings: the middleware, directly after SecurityMiddleware and before everything else, and its storage class.

Source: WhiteNoise: Using WhiteNoise with Django

CompressedManifestStaticFilesStorage combines Django’s manifest hashing with compression (gzip files, and Brotli when the package is installed, are written next to the originals only when they are smaller). The alternative CompressedStaticFilesStorage compresses without hashing. After collectstatic, Gunicorn served the site and curl showed what the browser would see:

Source: WhiteNoise: Using WhiteNoise with Django

The two Cache-Control values show the design. WhiteNoise recognises hashed names and marks them cacheable forever and immutable; unhashed files get a short max-age (WHITENOISE_MAX_AGE, 60 seconds by default). Access-Control-Allow-Origin: * comes from WHITENOISE_ALLOW_ALL_ORIGINS (default True) so that fonts and canvas images keep working when a CDN serves the files from another domain. The other settings you will meet are WHITENOISE_ROOT (serve a folder such as one with robots.txt at the site root), WHITENOISE_USE_FINDERS and WHITENOISE_AUTOREFRESH (both default to DEBUG; development conveniences), WHITENOISE_INDEX_FILE, WHITENOISE_MIMETYPES and WHITENOISE_ADD_HEADERS_FUNCTION. WhiteNoise 6.12.0 lists Django up to 6.0 in its package classifiers; the scratch project ran it on Django 6.1.1 without problems, but treat that as "works", not as a stated guarantee. WhiteNoise serves static files only. Uploaded media do not belong to it (see File Uploads & Storage).

A content delivery network caches files at the edge. There are two ways to use one, and they combine well with hashed names.

The first is the pull CDN: the CDN’s origin is your site (the WhiteNoise or Nginx host) and it fetches and caches files on demand. Nothing changes in Django except STATIC_URL, which becomes the CDN URL. The static tag, the manifest and form Media then all produce CDN URLs (the official Media examples show the same effect).

Source: Django: STATIC_URL

Source: Django: Serving static files from a cloud service or CDN

The second is the push model: collectstatic uploads straight to object storage. The how-to shows the shape, a custom backend named in STORAGES["staticfiles"]:

Source: Django: Serving static files from a cloud service or CDN

The class is a placeholder, as in the how-to. The django-storages S3 backend that File Uploads & Storage runs against a local S3 look-alike is the real starting point; a subclass that mixes in ManifestFilesMixin gives hashed names on a bucket. No real bucket or CDN was used for this page, so bucket policies, CORS rules for fonts and cache invalidation are exactly the parts it cannot vouch for. Two practical rules apply to any CDN: keep hashed names (so no invalidation is ever needed for static files), and never put user-specific or private responses behind the static prefix.

The configuration must agree with Django on one thing: the URL prefix. base is the URL under which the build will be served, so it is STATIC_URL plus the prefix that STATICFILES_DIRS assigns to Vite’s output folder. build.manifest makes Vite write .vite/manifest.json, which maps each entry to its hashed output files.

Source: Vite: Backend integration

Source: Vite: Building for production

The Vite guide names the entry option build.rolldownOptions.input (the bundler underneath Vite 8 is Rolldown); older Vite releases and many tutorials call it build.rollupOptions.input, so copied configurations may need that rename. The main.js entry here imports a stylesheet, which is why the manifest lists a css file for it. A real manifest also has imports (shared chunks that should be preloaded) and dynamicImports.

Expose the output folder under the prefix, tell Django where the manifest is, and add a switch for the dev server:

Source: Django: STATICFILES_DIRS

Because the dev server runs with base set, its URLs include the prefix: http://localhost:5173/static/vite/@vite/client answered 200 (with Access-Control-Allow-Origin echoing the configured origin) while http://localhost:5173/@vite/client answered 404. The setting above therefore ends in /static/vite. The template tag renders the dev-server tags or the production tags:

Source: Vite: Backend integration and Django: simple tags

The tag follows the order the Vite guide prescribes for a backend (stylesheets of imported chunks, then the entry’s stylesheets, the entry script, optional module preloads) and builds its HTML with format_html, so file names are escaped. Authoring tags is covered on Custom Template Tags & Filters. In a template:

Source: Vite: Backend integration

With the production settings, collectstatic and the page rendered through the test client produced:

Source: Django: ManifestStaticFilesStorage

Notice the double hash: Vite already fingerprints its output, and Django adds its own on top. The result works (the original Vite-named files are still in STATIC_ROOT, so a modulepreload or a JavaScript import that uses Vite’s names finds them), but it is redundant. If a project prefers one hash, keep the Vite output out of collectstatic’s post-processing (a storage subclass that skips the `vite/ prefix) or serve dist/ directly from the web server. With VITE_DEV_SERVER set the same template produces the dev tags instead. The tests assert both:

Source: Vite: Backend integration

The hand-written tag keeps the mechanism visible. Packages exist that package the same idea (django-vite is the best known; its PyPI classifiers, checked 2026-10-03 for version 3.2.0, list Django only up to 4.2, and it was not run for this page), so evaluate one against your Django version before adopting it. A project that uses React with Vite and wants fast refresh must also inject the React refresh preamble that the Vite guide shows; the tag above does not.

The order matters in a pipeline: install npm dependencies, vite build, then collectstatic, because collectstatic copies whatever is in frontend/dist at that moment. In Docker this is a multi-stage build (a Node stage produces dist, the Python stage copies it and collects). The general production concerns are on Deployment; the front-end build concerns are on HTML & CSS performance and build optimization.

The catch-all view returns the shell for every URL the router owns on the client, so deep links and page reloads work; the build version endpoint lets a long-lived tab notice that a new deployment replaced its assets (this uses the manifest_hash of the manifest storage from Tuning the storage).

Source: Django: ManifestStaticFilesStorage.manifest_hash

Source: Django: Using regular expressions and manifest_hash

Source: Django: Overriding settings

URL ordering matters in a real project: API, admin and static prefixes first, and the catch-all last, otherwise it hides them. Authentication in this shape is the plain session cookie plus the CSRF token of Security; the SPA reads the csrftoken cookie and sends it in the X-CSRFToken header. The API itself is on Django REST Framework and Django Ninja.

When the SPA lives elsewhere, the browser enforces the same-origin policy and Django must opt in to cross-origin requests; the mechanism, the preflight and the Origin checks are explained on What is CORS?. Session cookies across sites also bring SameSite and CSRF trusted-origin decisions, so many teams pick token authentication for this shape. The decision needs the details from the security page and the API pages, not from this one. What static files add: the SPA is built and deployed by its own pipeline, and Django serves none of it.

The front-end sections of this site cover the other half of the pairing: React starts at Getting Started with React and its build story is on Build and Deployment; Vue’s setup and Vite tooling are on Tooling and Project Setup with deployment on Performance and Deployment; Angular starts at Getting Started with Angular and ships through its own CLI build, covered on Production and Performance. The Angular CLI build writes its own index.html with the hashed file names already injected, so for Angular the Django-served option means copying the CLI build output into a STATICFILES_DIRS folder and serving that index.html from the catch-all view, rather than reading a Vite manifest (this combination was not run here). React and Vue projects created with Vite can reuse the tag shown above unchanged.