Files
FireworksApp/README.md
T

94 lines
5.0 KiB
Markdown

# 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 <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`.