# 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 ```sh 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: ```django {% 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 ```sh 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: ```text 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 :` | 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`.