diff --git a/README.md b/README.md index 9f778b1..76f9397 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,142 @@ # Django Vite Integration of [ViteJS](https://vitejs.dev/) in a Django project. + +## Installation + +### Django + +``` +pip install django-vite +``` + +Add `django_vite` to your `INSTALLED_APPS` in your `settings.py` +(before your apps that are using it). + +```python +INSTALLED_APPS = [ + ... + 'django_vite', + ... +] +``` + +### ViteJS + +Follow instructions on [https://vitejs.dev/guide/](https://vitejs.dev/guide/). +And mostly the SSR part. + +Then in your ViteJS config file : + +- Set the `root` options the same as your `STATIC_URL` Django setting. +- Set the `build.outDir` path to where you want the assets to compiled. +- Set the `build.manifest` options to `true`. +- As you are in SSR and not in SPA, you don't have an `index.html` that + ViteJS can use to determine which files to compile. You need to tell it + directly. In your ViteJS config file add the following : + +```javascript +export default defineConfig({ + build { + ... + rollupOptions: { + input: { + : '' + } + } + } +} +``` + +## Usage + +### Configuration + +- Define a setting variable in your `settings.py` named `DJANGO_VITE_ASSETS_PATH` + containing the absolute path to where your assets are built. + + - This must correspond to your `build.outDir` in your ViteJS configuration. + - The `DJANGO_VITE_ASSETS_PATH` must be included in your `STATICFILES_DIRS` + Django setting. + +- Define a setting variable in your `settings.py` named `DJANGO_VITE_DEV_MODE` + containing a boolean defining if you want to include assets in development + mode or production mode. + + - In development mode, assets are included as modules using the ViteJS + webserver. This will enable HMR for your assets. + - In production mode, assets are included as standard assets + (no ViteJS webserver and HMR) like default Django static files. + This means that your assets must be compiled with ViteJS before. + - This setting may be set as the same value as your `DEBUG` setting in + Django. But you can do what is good for yout needs. + +### Template tags + +Include this in your base HTML template file. + +``` +{% load django_vite %} +``` + +Then in your `` element add this : + +``` +{% vite_hmr_client %} +``` + +- This will add a `