tessl/pypi-django-vite

Integration of Vite in a Django project.

—

Pending

Overview

Eval results

Files

Configuration

Name: tessl/pypi-django-vite
Author: tessl

Django-vite's configuration system supports both single-app and multi-app Vite setups, with separate settings for development and production modes.

Capabilities

Basic Configuration

Configure django-vite in Django settings using the DJANGO_VITE setting.

# In settings.py
DJANGO_VITE = {
    "default": {
        "dev_mode": True,
        "dev_server_port": 5173,
        "static_url_prefix": "",
        "manifest_path": None,
    }
}

Single App Configuration Example:

DJANGO_VITE = {
    "default": {
        "dev_mode": DEBUG,
        "dev_server_protocol": "http",
        "dev_server_host": "localhost", 
        "dev_server_port": 5173,
        "static_url_prefix": "",
        "manifest_path": BASE_DIR / "static" / "manifest.json",
        "legacy_polyfills_motif": "legacy-polyfills",
        "ws_client_url": "@vite/client",
        "react_refresh_url": "@react-refresh",
    }
}

Multi-App Configuration

Configure multiple Vite applications within a single Django project.

Multi-App Configuration Example:

DJANGO_VITE = {
    "frontend": {
        "dev_mode": DEBUG,
        "dev_server_port": 5173,
        "static_url_prefix": "frontend/",
        "manifest_path": BASE_DIR / "static" / "frontend" / "manifest.json",
    },
    "admin": {
        "dev_mode": DEBUG,
        "dev_server_port": 5174,
        "static_url_prefix": "admin/",
        "manifest_path": BASE_DIR / "static" / "admin" / "manifest.json",
    }
}

Using Multi-App Configuration in Templates:

{% load django_vite %}

<!-- Frontend app assets -->
{% vite_asset 'src/main.js' app='frontend' %}

<!-- Admin app assets -->  
{% vite_asset 'src/admin.js' app='admin' %}

Configuration Class

Central configuration class defining all django-vite settings.

class DjangoViteConfig(NamedTuple):
    """Configuration parameters for a DjangoViteAppClient."""
    
    dev_mode: bool = False
    dev_server_protocol: str = "http" 
    dev_server_host: str = "localhost"
    dev_server_port: int = 5173
    static_url_prefix: str = ""
    manifest_path: Optional[Union[Path, str]] = None
    legacy_polyfills_motif: str = "legacy-polyfills"
    ws_client_url: str = "@vite/client"
    react_refresh_url: str = "@react-refresh"
    app_client_class: str = "django_vite.core.asset_loader.DjangoViteAppClient"

Configuration Parameters

Development vs Production Mode

dev_mode: bool = False

Controls whether django-vite operates in development or production mode:

Development (True): Assets served from Vite dev server, HMR enabled
Production (False): Assets served from Django static files, manifest.json required

Usage Example:

DJANGO_VITE = {
    "default": {
        "dev_mode": DEBUG,  # Automatically switch based on Django DEBUG setting
    }
}

Development Server Settings

dev_server_protocol: str = "http"
dev_server_host: str = "localhost" 
dev_server_port: int = 5173

Configure connection to Vite development server.

Usage Example:

DJANGO_VITE = {
    "default": {
        "dev_server_protocol": "https",  # For HTTPS dev server
        "dev_server_host": "0.0.0.0",   # For Docker/remote access
        "dev_server_port": 3000,        # Custom port
    }
}

Static File Settings

static_url_prefix: str = ""

Prefix for static URL paths, useful for CDN integration or multi-app setups.

CDN Example:

DJANGO_VITE = {
    "default": {
        "static_url_prefix": "assets/",
    }
}

Manifest Configuration

manifest_path: Optional[Union[Path, str]] = None

Path to Vite's manifest.json file. If not provided, defaults to STATIC_ROOT/static_url_prefix/manifest.json.

Custom Manifest Path Example:

DJANGO_VITE = {
    "default": {
        "manifest_path": BASE_DIR / "frontend" / "dist" / "manifest.json",
    }
}

Legacy Browser Support

legacy_polyfills_motif: str = "legacy-polyfills"

Pattern to identify polyfills in manifest.json when using @vitejs/plugin-legacy.

Usage with Legacy Plugin:

DJANGO_VITE = {
    "default": {
        "legacy_polyfills_motif": "polyfills-legacy",  # Custom motif
    }
}

Hot Module Replacement Settings

ws_client_url: str = "@vite/client"
react_refresh_url: str = "@react-refresh"

Configure HMR and React refresh URLs for development.

Custom HMR Configuration:

DJANGO_VITE = {
    "default": {
        "ws_client_url": "/@vite/client",
        "react_refresh_url": "/@react-refresh",
    }
}

Custom Client Class

app_client_class: str = "django_vite.core.asset_loader.DjangoViteAppClient"

Specify a custom client class for advanced customization.

Custom Client Example:

# Custom client class
class CustomViteClient(DjangoViteAppClient):
    def generate_vite_asset(self, path, **kwargs):
        # Custom asset generation logic
        return super().generate_vite_asset(path, **kwargs)

DJANGO_VITE = {
    "default": {
        "app_client_class": "myapp.vite.CustomViteClient",
    }
}

Legacy Settings Support

Django-vite supports legacy individual settings for backward compatibility (deprecated).

# Complete legacy settings mapping (deprecated - use DJANGO_VITE instead)
LEGACY_DJANGO_VITE_SETTINGS = {
    "DJANGO_VITE_DEV_MODE": "dev_mode",
    "DJANGO_VITE_DEV_SERVER_PROTOCOL": "dev_server_protocol", 
    "DJANGO_VITE_DEV_SERVER_HOST": "dev_server_host",
    "DJANGO_VITE_DEV_SERVER_PORT": "dev_server_port",
    "DJANGO_VITE_STATIC_URL_PREFIX": "static_url_prefix",
    "DJANGO_VITE_MANIFEST_PATH": "manifest_path",
    "DJANGO_VITE_LEGACY_POLYFILLS_MOTIF": "legacy_polyfills_motif",
    "DJANGO_VITE_WS_CLIENT_URL": "ws_client_url",
    "DJANGO_VITE_REACT_REFRESH_URL": "react_refresh_url",
    "DJANGO_VITE_ASSETS_PATH": None,  # Deprecated, no longer used
}

# Example legacy settings (deprecated)
DJANGO_VITE_DEV_MODE = True
DJANGO_VITE_DEV_SERVER_HOST = "localhost"
DJANGO_VITE_DEV_SERVER_PORT = 5173
DJANGO_VITE_STATIC_URL_PREFIX = ""
DJANGO_VITE_MANIFEST_PATH = None
DJANGO_VITE_LEGACY_POLYFILLS_MOTIF = "legacy-polyfills"
DJANGO_VITE_WS_CLIENT_URL = "@vite/client"
DJANGO_VITE_REACT_REFRESH_URL = "@react-refresh"

Migration Example:

# Old way (deprecated)
DJANGO_VITE_DEV_MODE = DEBUG
DJANGO_VITE_DEV_SERVER_PORT = 5173

# New way (recommended)
DJANGO_VITE = {
    "default": {
        "dev_mode": DEBUG,
        "dev_server_port": 5173,
    }
}

Configuration Validation

Django-vite includes Django system checks to validate configuration.

def check_loader_instance(**kwargs) -> List[Warning]:
    """Django system check function for validating configurations."""

System Check Messages:

django_vite.W001: Manifest file validation errors
Warnings include hints for resolving configuration issues

Manual Configuration Check:

from django_vite.core.asset_loader import DjangoViteAssetLoader

# Check all configurations
loader = DjangoViteAssetLoader.instance()
warnings = loader.check()
for warning in warnings:
    print(f"{warning.id}: {warning.msg}")

Install with Tessl CLI