5.0 KiB
Portable Django + Vite integration
This repository originally used only Django native static files. The Vite integration below is now wired into the rendered public pages and custom Admin pages: shared assets live in frontend/src/, while Django still owns template rendering and its native static files.
What is included
vite_integration/: reusable Django app and{% vite_asset %}tagfrontend/src/entries/: one Vite entry module per rendered page, with sharedstyles/andscripts/modulesvite.config.mjs: Vite output, manifest, host, port, and entry configurationpackage.json:dev,django,vite, andbuildscriptsscripts/dev-django.mjs: configurable backend process forconcurrently.env.vite.example: documented development and production variables
Vite builds into vite_integration/static/vite/. Because this is a Django app static directory, Django's staticfiles finders and collectstatic discover the manifest and built assets automatically.
Prerequisites
- Python and the Django environment for the project
- Node.js 20+ and npm
- A configured Django
STATIC_URLandSTATIC_ROOTfor production
Install in this repository
cp .env.vite.example .env.vite
npm install
set -a; . ./.env.vite; set +a
npm run dev
npm run dev starts Django and Vite together using concurrently. It runs python manage.py runserver 127.0.0.1:8000 and Vite on 127.0.0.1:5173 by default. Change the variables before starting it, or set DJANGO_DEV_COMMAND to replace the backend command completely.
Add an entry point to a template
Choose an entry point and include it once in the relevant base template:
{% load vite %}
{% vite_asset "frontend/src/entries/site.js" %}
The tag renders Vite's HMR client and the entry point when VITE_USE_DEV_SERVER=true. Otherwise it reads Vite's manifest and renders the fingerprinted CSS and JavaScript under Django's static URL. See vite_integration/templates/vite_integration/example_assets.html for the same snippet.
Production
set -a; . ./.env.vite; set +a
VITE_USE_DEV_SERVER=false npm run build
VITE_USE_DEV_SERVER=false python manage.py collectstatic --noinput
Build before collectstatic. The generated vite/.vite/manifest.json and vite/assets/* are collected with all other Django static files. Do not use the Vite development server in production.
Reuse in a fresh Django project
Copy these files and directories:
vite_integration/
frontend/src/
scripts/dev-django.mjs
vite.config.mjs
package.json
.env.vite.example
Create frontend/src/entries/site.js (or another entry beneath VITE_ENTRY_DIR) that imports the page CSS and JavaScript. Then add vite_integration to INSTALLED_APPS, add the template tag to a base template, configure STATIC_URL/STATIC_ROOT, install npm packages, and use the development or production commands above. The integration contains no application names, routes, or backend URLs.
Configuration values to customize
| Variable/setting | Default | Purpose |
|---|---|---|
DJANGO_DEV_COMMAND |
python manage.py runserver <host>:<port> |
Complete backend development command |
DJANGO_HOST, DJANGO_PORT |
127.0.0.1, 8000 |
Default backend bind address |
VITE_HOST, VITE_PORT |
127.0.0.1, 5173 |
Vite bind address and port |
VITE_DEV_SERVER_URL |
http://127.0.0.1:5173/ |
URL Django templates use for HMR |
VITE_DEV_BASE_URL |
/ |
Development-only Vite base path |
VITE_USE_DEV_SERVER |
false |
Enables HMR tags; set only for development |
VITE_ENTRY_DIR |
frontend/src/entries |
Directory Vite scans for page entry points |
VITE_ENTRY |
unset | Optional comma-separated explicit entry point list |
VITE_OUT_DIR |
vite_integration/static/vite |
Build output relative to project root |
VITE_STATIC_PREFIX |
vite |
Django static namespace for built files |
VITE_BASE_URL |
/static/vite/ |
Public base URL emitted by Vite |
VITE_MANIFEST_PATH |
staticfiles finder | Optional explicit manifest location |
Django settings override environment variables with the same names. VITE_BASE_URL must equal the public STATIC_URL followed by VITE_STATIC_PREFIX (for example, /static/vite/). A .env.vite file is not automatically read by Django; export/source it in the process manager, shell, container, or deployment configuration.
Troubleshooting
- Vite manifest not found: run
npm run buildbeforecollectstatic; check thatVITE_OUT_DIRends below a Django appstatic/directory and that its final segment matchesVITE_STATIC_PREFIX. - Browser cannot reach HMR: set
VITE_DEV_SERVER_URLto the browser-reachable Vite address, and use matchingVITE_HOST/VITE_PORT. For containers or remote browsers this is often0.0.0.0for the host plus a public hostname for the URL. - A page fails in development: set
VITE_USE_DEV_SERVER=trueonly whilenpm run viteornpm run devis running. - Assets return 404 after deployment: rerun both the build and
collectstatic; ensure the web server servesSTATIC_ROOTatSTATIC_URL.