92 lines
4.7 KiB
Markdown
92 lines
4.7 KiB
Markdown
# 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 %}` tag
|
|
- `frontend/src/main.js`: replaceable example entry point
|
|
- `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/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
|
|
|
|
```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
|
|
```
|
|
|
|
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 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`.
|