0
# Django Vite
1
2
Integration of ViteJS (a modern frontend build tool) and Django web framework, enabling developers to use Vite's fast development server, hot module replacement (HMR), and optimized production builds within Django projects.
3
4
## Package Information
5
6
- **Package Name**: django-vite
7
- **Package Type**: Python library
8
- **Language**: Python
9
- **Installation**: `pip install django-vite`
10
- **Django Compatibility**: Django 3.2+
11
- **Python Versions**: 3.8, 3.9, 3.10, 3.11, 3.12
12
13
## Core Imports
14
15
```python
16
from django_vite import DjangoViteConfig
17
```
18
19
For Django template usage:
20
```python
21
# In templates, load the template tags
22
{% load django_vite %}
23
```
24
25
For programmatic asset loading:
26
```python
27
from django_vite.core.asset_loader import DjangoViteAssetLoader
28
```
29
30
For tag generation utilities:
31
```python
32
from django_vite.core.tag_generator import TagGenerator, attrs_to_str
33
```
34
35
For exception handling:
36
```python
37
from django_vite.core.exceptions import (
38
DjangoViteManifestError,
39
DjangoViteAssetNotFoundError,
40
DjangoViteConfigNotFoundError
41
)
42
```
43
44
## Basic Usage
45
46
### Django Settings Configuration
47
48
```python
49
# settings.py
50
INSTALLED_APPS = [
51
# ... other apps
52
'django_vite',
53
# ... your apps that use django-vite
54
]
55
56
# Basic configuration
57
DJANGO_VITE = {
58
"default": {
59
"dev_mode": True, # Set to False for production
60
"dev_server_port": 5173,
61
"static_url_prefix": "",
62
}
63
}
64
```
65
66
### Template Usage
67
68
```html
69
<!-- templates/base.html -->
70
{% load django_vite %}
71
<!DOCTYPE html>
72
<html>
73
<head>
74
<title>My Django App</title>
75
<!-- Include Vite assets -->
76
{% vite_asset 'src/main.js' %}
77
</head>
78
<body>
79
<!-- HMR client for development -->
80
{% vite_hmr_client %}
81
82
<!-- React refresh for development -->
83
{% vite_react_refresh %}
84
85
<!-- Your content -->
86
</body>
87
</html>
88
```
89
90
### Development vs Production
91
92
In **development mode** (`dev_mode: True`):
93
- Assets are served from Vite development server
94
- Hot Module Replacement (HMR) enabled
95
- React refresh support
96
- No manifest.json required
97
98
In **production mode** (`dev_mode: False`):
99
- Assets served from Django static files
100
- Reads manifest.json for asset dependencies
101
- Generates optimized script and link tags
102
- Supports legacy browser polyfills
103
104
## Architecture
105
106
Django-vite follows a modular architecture:
107
108
- **DjangoViteAssetLoader**: Singleton managing multiple app configurations
109
- **DjangoViteAppClient**: Handles asset generation for individual Vite apps
110
- **ManifestClient**: Parses and provides access to Vite's manifest.json
111
- **Template Tags**: Django template integration layer
112
- **TagGenerator**: HTML tag generation utilities
113
114
This design supports multi-app configurations where different parts of a Django project can use separate Vite configurations while sharing the same asset loading infrastructure.
115
116
## Capabilities
117
118
### Configuration Management
119
120
Configuration system supporting both single-app and multi-app Vite setups with development and production modes.
121
122
```python { .api }
123
class DjangoViteConfig(NamedTuple):
124
dev_mode: bool = False
125
dev_server_protocol: str = "http"
126
dev_server_host: str = "localhost"
127
dev_server_port: int = 5173
128
static_url_prefix: str = ""
129
manifest_path: Optional[Union[Path, str]] = None
130
legacy_polyfills_motif: str = "legacy-polyfills"
131
ws_client_url: str = "@vite/client"
132
react_refresh_url: str = "@react-refresh"
133
app_client_class: str = "django_vite.core.asset_loader.DjangoViteAppClient"
134
```
135
136
[Configuration](./configuration.md)
137
138
### Template Tags
139
140
Django template tags for including Vite assets, HMR client, React refresh, and legacy browser support in templates.
141
142
```python { .api }
143
def vite_asset(path: str, app: str = "default", **kwargs) -> str: ...
144
def vite_asset_url(path: str, app: str = "default") -> str: ...
145
def vite_preload_asset(path: str, app: str = "default") -> str: ...
146
def vite_hmr_client(app: str = "default", **kwargs) -> str: ...
147
def vite_react_refresh(app: str = "default", **kwargs) -> str: ...
148
def vite_legacy_polyfills(app: str = "default", nomodule: bool = True, **kwargs) -> str: ...
149
def vite_legacy_asset(path: str, app: str = "default", **kwargs) -> str: ...
150
```
151
152
[Template Tags](./template-tags.md)
153
154
### Asset Loading
155
156
Core asset loading system with manifest parsing, URL generation, and programmatic asset management.
157
158
```python { .api }
159
class DjangoViteAssetLoader:
160
@classmethod
161
def instance(cls) -> 'DjangoViteAssetLoader': ...
162
def generate_vite_asset(self, path: str, app: str = "default", **kwargs) -> str: ...
163
def generate_vite_asset_url(self, path: str, app: str = "default") -> str: ...
164
def preload_vite_asset(self, path: str, app: str = "default") -> str: ...
165
def check(self, **kwargs) -> List[Warning]: ...
166
167
class DjangoViteAppClient:
168
def __init__(self, config: DjangoViteConfig, app_name: str = "default"): ...
169
def generate_vite_asset(self, path: str, **kwargs) -> str: ...
170
def get_dev_server_url(self, path: str) -> str: ...
171
def get_production_server_url(self, path: str) -> str: ...
172
173
class ManifestClient:
174
def __init__(self, config: DjangoViteConfig, app_name: str = "default"): ...
175
def get(self, path: str) -> ManifestEntry: ...
176
def check(self) -> List[Warning]: ...
177
```
178
179
[Asset Loading](./asset-loading.md)
180
181
### Tag Generation Utilities
182
183
Low-level HTML tag generation utilities used by the asset loading system.
184
185
```python { .api }
186
class TagGenerator:
187
@staticmethod
188
def script(src: str, attrs: Dict[str, str]) -> str: ...
189
@staticmethod
190
def stylesheet(href: str, attrs: Optional[Dict[str, str]] = None) -> str: ...
191
@staticmethod
192
def stylesheet_preload(href: str, attrs: Optional[Dict[str, str]] = None) -> str: ...
193
@staticmethod
194
def preload(href: str, attrs: Dict[str, str]) -> str: ...
195
196
def attrs_to_str(attrs: Dict[str, str]) -> str: ...
197
```
198
199
### Django App Configuration
200
201
Django app configuration and system checks for django-vite integration.
202
203
```python { .api }
204
class DjangoViteAppConfig(AppConfig):
205
name: str = "django_vite"
206
verbose_name: str = "Django Vite"
207
208
def ready(self) -> None: ...
209
210
def check_loader_instance(**kwargs) -> List[Warning]:
211
"""Django system check function for validating configurations."""
212
```
213
214
## Exception Types
215
216
```python { .api }
217
class DjangoViteManifestError(RuntimeError):
218
"""Manifest parsing failed."""
219
220
class DjangoViteAssetNotFoundError(RuntimeError):
221
"""Vite Asset could not be found."""
222
223
class DjangoViteConfigNotFoundError(RuntimeError):
224
"""DjangoViteConfig not found in DJANGO_VITE settings."""
225
```
226
227
## Common Types
228
229
```python { .api }
230
class ManifestEntry(NamedTuple):
231
file: str
232
src: Optional[str] = None
233
isEntry: Optional[bool] = False
234
isDynamicEntry: Optional[bool] = False
235
css: Optional[List[str]] = []
236
imports: Optional[List[str]] = []
237
dynamicImports: Optional[List[str]] = []
238
```