# 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`. ## Interface translations English text in templates and Python is the source language. Dutch translations live in `locale/nl/LC_MESSAGES/django.po`; the compiled `django.mo` is used at runtime. Logged-in users choose their language at `/settings/`. Visitors use the language switcher in the public navigation, which saves Django's standard language cookie. URLs and stored status or source codes do not change with the language. Update translations after changing user-facing source text: ```bash python manage.py makemessages -l nl --ignore=node_modules --ignore=staticfiles --ignore='*.orig' # Edit locale/nl/LC_MESSAGES/django.po python manage.py compilemessages ``` The small amount of JavaScript UI text is translated by Django in `templates/js_translations.html` and read from `window.BOOMCAST_I18N`. After changing JavaScript, run `npm run build` and `python manage.py collectstatic --noinput` for production. Classifier class names, API keys, sensor tokens, H3 values and stored source/status values remain language-neutral.