Portable Django + Vite integration
This repository did not previously contain Vite configuration, package scripts, a manifest, or Vite-aware Django templates. Its only asset setup was Django native static files. The files below add an isolated, reusable Vite integration without attaching any Vite bundle to existing pages.
What is included
vite_integration/: reusable Django app and{% vite_asset %}tagfrontend/src/main.js: replaceable example entry pointvite.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/main.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
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_USE_DEV_SERVER |
false |
Enables HMR tags; set only for development |
VITE_ENTRY |
frontend/src/main.js |
Vite Rollup entry point |
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.