0
# Configuration
1
2
Django-vite's configuration system supports both single-app and multi-app Vite setups, with separate settings for development and production modes.
3
4
## Capabilities
5
6
### Basic Configuration
7
8
Configure django-vite in Django settings using the `DJANGO_VITE` setting.
9
10
```python { .api }
11
# In settings.py
12
DJANGO_VITE = {
13
"default": {
14
"dev_mode": True,
15
"dev_server_port": 5173,
16
"static_url_prefix": "",
17
"manifest_path": None,
18
}
19
}
20
```
21
22
**Single App Configuration Example:**
23
```python
24
DJANGO_VITE = {
25
"default": {
26
"dev_mode": DEBUG,
27
"dev_server_protocol": "http",
28
"dev_server_host": "localhost",
29
"dev_server_port": 5173,
30
"static_url_prefix": "",
31
"manifest_path": BASE_DIR / "static" / "manifest.json",
32
"legacy_polyfills_motif": "legacy-polyfills",
33
"ws_client_url": "@vite/client",
34
"react_refresh_url": "@react-refresh",
35
}
36
}
37
```
38
39
### Multi-App Configuration
40
41
Configure multiple Vite applications within a single Django project.
42
43
**Multi-App Configuration Example:**
44
```python
45
DJANGO_VITE = {
46
"frontend": {
47
"dev_mode": DEBUG,
48
"dev_server_port": 5173,
49
"static_url_prefix": "frontend/",
50
"manifest_path": BASE_DIR / "static" / "frontend" / "manifest.json",
51
},
52
"admin": {
53
"dev_mode": DEBUG,
54
"dev_server_port": 5174,
55
"static_url_prefix": "admin/",
56
"manifest_path": BASE_DIR / "static" / "admin" / "manifest.json",
57
}
58
}
59
```
60
61
**Using Multi-App Configuration in Templates:**
62
```html
63
{% load django_vite %}
64
65
<!-- Frontend app assets -->
66
{% vite_asset 'src/main.js' app='frontend' %}
67
68
<!-- Admin app assets -->
69
{% vite_asset 'src/admin.js' app='admin' %}
70
```
71
72
### Configuration Class
73
74
Central configuration class defining all django-vite settings.
75
76
```python { .api }
77
class DjangoViteConfig(NamedTuple):
78
"""Configuration parameters for a DjangoViteAppClient."""
79
80
dev_mode: bool = False
81
dev_server_protocol: str = "http"
82
dev_server_host: str = "localhost"
83
dev_server_port: int = 5173
84
static_url_prefix: str = ""
85
manifest_path: Optional[Union[Path, str]] = None
86
legacy_polyfills_motif: str = "legacy-polyfills"
87
ws_client_url: str = "@vite/client"
88
react_refresh_url: str = "@react-refresh"
89
app_client_class: str = "django_vite.core.asset_loader.DjangoViteAppClient"
90
```
91
92
### Configuration Parameters
93
94
#### Development vs Production Mode
95
96
```python { .api }
97
dev_mode: bool = False
98
```
99
100
Controls whether django-vite operates in development or production mode:
101
- **Development** (`True`): Assets served from Vite dev server, HMR enabled
102
- **Production** (`False`): Assets served from Django static files, manifest.json required
103
104
**Usage Example:**
105
```python
106
DJANGO_VITE = {
107
"default": {
108
"dev_mode": DEBUG, # Automatically switch based on Django DEBUG setting
109
}
110
}
111
```
112
113
#### Development Server Settings
114
115
```python { .api }
116
dev_server_protocol: str = "http"
117
dev_server_host: str = "localhost"
118
dev_server_port: int = 5173
119
```
120
121
Configure connection to Vite development server.
122
123
**Usage Example:**
124
```python
125
DJANGO_VITE = {
126
"default": {
127
"dev_server_protocol": "https", # For HTTPS dev server
128
"dev_server_host": "0.0.0.0", # For Docker/remote access
129
"dev_server_port": 3000, # Custom port
130
}
131
}
132
```
133
134
#### Static File Settings
135
136
```python { .api }
137
static_url_prefix: str = ""
138
```
139
140
Prefix for static URL paths, useful for CDN integration or multi-app setups.
141
142
**CDN Example:**
143
```python
144
DJANGO_VITE = {
145
"default": {
146
"static_url_prefix": "assets/",
147
}
148
}
149
```
150
151
#### Manifest Configuration
152
153
```python { .api }
154
manifest_path: Optional[Union[Path, str]] = None
155
```
156
157
Path to Vite's manifest.json file. If not provided, defaults to `STATIC_ROOT/static_url_prefix/manifest.json`.
158
159
**Custom Manifest Path Example:**
160
```python
161
DJANGO_VITE = {
162
"default": {
163
"manifest_path": BASE_DIR / "frontend" / "dist" / "manifest.json",
164
}
165
}
166
```
167
168
#### Legacy Browser Support
169
170
```python { .api }
171
legacy_polyfills_motif: str = "legacy-polyfills"
172
```
173
174
Pattern to identify polyfills in manifest.json when using `@vitejs/plugin-legacy`.
175
176
**Usage with Legacy Plugin:**
177
```python
178
DJANGO_VITE = {
179
"default": {
180
"legacy_polyfills_motif": "polyfills-legacy", # Custom motif
181
}
182
}
183
```
184
185
#### Hot Module Replacement Settings
186
187
```python { .api }
188
ws_client_url: str = "@vite/client"
189
react_refresh_url: str = "@react-refresh"
190
```
191
192
Configure HMR and React refresh URLs for development.
193
194
**Custom HMR Configuration:**
195
```python
196
DJANGO_VITE = {
197
"default": {
198
"ws_client_url": "/@vite/client",
199
"react_refresh_url": "/@react-refresh",
200
}
201
}
202
```
203
204
#### Custom Client Class
205
206
```python { .api }
207
app_client_class: str = "django_vite.core.asset_loader.DjangoViteAppClient"
208
```
209
210
Specify a custom client class for advanced customization.
211
212
**Custom Client Example:**
213
```python
214
# Custom client class
215
class CustomViteClient(DjangoViteAppClient):
216
def generate_vite_asset(self, path, **kwargs):
217
# Custom asset generation logic
218
return super().generate_vite_asset(path, **kwargs)
219
220
DJANGO_VITE = {
221
"default": {
222
"app_client_class": "myapp.vite.CustomViteClient",
223
}
224
}
225
```
226
227
### Legacy Settings Support
228
229
Django-vite supports legacy individual settings for backward compatibility (deprecated).
230
231
```python { .api }
232
# Complete legacy settings mapping (deprecated - use DJANGO_VITE instead)
233
LEGACY_DJANGO_VITE_SETTINGS = {
234
"DJANGO_VITE_DEV_MODE": "dev_mode",
235
"DJANGO_VITE_DEV_SERVER_PROTOCOL": "dev_server_protocol",
236
"DJANGO_VITE_DEV_SERVER_HOST": "dev_server_host",
237
"DJANGO_VITE_DEV_SERVER_PORT": "dev_server_port",
238
"DJANGO_VITE_STATIC_URL_PREFIX": "static_url_prefix",
239
"DJANGO_VITE_MANIFEST_PATH": "manifest_path",
240
"DJANGO_VITE_LEGACY_POLYFILLS_MOTIF": "legacy_polyfills_motif",
241
"DJANGO_VITE_WS_CLIENT_URL": "ws_client_url",
242
"DJANGO_VITE_REACT_REFRESH_URL": "react_refresh_url",
243
"DJANGO_VITE_ASSETS_PATH": None, # Deprecated, no longer used
244
}
245
246
# Example legacy settings (deprecated)
247
DJANGO_VITE_DEV_MODE = True
248
DJANGO_VITE_DEV_SERVER_HOST = "localhost"
249
DJANGO_VITE_DEV_SERVER_PORT = 5173
250
DJANGO_VITE_STATIC_URL_PREFIX = ""
251
DJANGO_VITE_MANIFEST_PATH = None
252
DJANGO_VITE_LEGACY_POLYFILLS_MOTIF = "legacy-polyfills"
253
DJANGO_VITE_WS_CLIENT_URL = "@vite/client"
254
DJANGO_VITE_REACT_REFRESH_URL = "@react-refresh"
255
```
256
257
**Migration Example:**
258
```python
259
# Old way (deprecated)
260
DJANGO_VITE_DEV_MODE = DEBUG
261
DJANGO_VITE_DEV_SERVER_PORT = 5173
262
263
# New way (recommended)
264
DJANGO_VITE = {
265
"default": {
266
"dev_mode": DEBUG,
267
"dev_server_port": 5173,
268
}
269
}
270
```
271
272
### Configuration Validation
273
274
Django-vite includes Django system checks to validate configuration.
275
276
```python { .api }
277
def check_loader_instance(**kwargs) -> List[Warning]:
278
"""Django system check function for validating configurations."""
279
```
280
281
**System Check Messages:**
282
- `django_vite.W001`: Manifest file validation errors
283
- Warnings include hints for resolving configuration issues
284
285
**Manual Configuration Check:**
286
```python
287
from django_vite.core.asset_loader import DjangoViteAssetLoader
288
289
# Check all configurations
290
loader = DjangoViteAssetLoader.instance()
291
warnings = loader.check()
292
for warning in warnings:
293
print(f"{warning.id}: {warning.msg}")
294
```