2026-10-01 17:29:29 +02:00
2026-10-01 17:29:29 +02:00
2026-10-01 17:29:29 +02:00
2026-10-01 17:29:29 +02:00
2026-10-01 17:29:29 +02:00
2026-10-01 16:38:13 +02:00
2026-10-01 17:29:29 +02:00
2026-10-01 16:38:13 +02:00
2026-10-01 17:29:29 +02:00
2026-09-26 20:59:01 +02:00
2026-09-26 20:59:01 +02:00
2026-10-01 16:38:13 +02:00

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 %} tag
  • frontend/src/entries/: one Vite entry module per rendered page, with shared styles/ and scripts/ modules
  • vite.config.mjs: Vite output, manifest, host, port, and entry configuration
  • package.json: dev, django, vite, and build scripts
  • scripts/dev-django.mjs: configurable backend process for concurrently
  • .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_URL and STATIC_ROOT for 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 build before collectstatic; check that VITE_OUT_DIR ends below a Django app static/ directory and that its final segment matches VITE_STATIC_PREFIX.
  • Browser cannot reach HMR: set VITE_DEV_SERVER_URL to the browser-reachable Vite address, and use matching VITE_HOST/VITE_PORT. For containers or remote browsers this is often 0.0.0.0 for the host plus a public hostname for the URL.
  • A page fails in development: set VITE_USE_DEV_SERVER=true only while npm run vite or npm run dev is running.
  • Assets return 404 after deployment: rerun both the build and collectstatic; ensure the web server serves STATIC_ROOT at STATIC_URL.
S
Description
No description provided
Readme
170 MiB
Languages
JavaScript 84.7%
CSS 6.3%
Python 6.3%
HTML 2.7%