litestar-vite 0.12.1__py3-none-any.whl → 0.13.0__py3-none-any.whl

litestar_vite/__init__.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from litestar_vite import inertia
+from litestar_vite.config import ViteConfig
+from litestar_vite.loader import ViteAssetLoader
+from litestar_vite.plugin import VitePlugin
+
+__all__ = ("ViteAssetLoader", "ViteConfig", "VitePlugin", "inertia")

litestar_vite/__metadata__.py

@@ -0,0 +1,18 @@
+"""Metadata for the Project."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, metadata, version
+
+__all__ = ("__project__", "__version__")
+
+try:
+    __version__ = version("litestar_vite")
+    """Version of the project."""
+    __project__ = metadata("litestar_vite")["Name"]
+    """Name of the project."""
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.0.0"
+    __project__ = "Litestar Vite"
+finally:
+    del version, PackageNotFoundError, metadata

litestar_vite/cli.py

@@ -0,0 +1,320 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from click import Context, group, option
+from click import Path as ClickPath
+from litestar.cli._utils import (
+    LitestarEnv,
+    LitestarGroup,
+)
+
+if TYPE_CHECKING:
+    from litestar import Litestar
+
+
+@group(cls=LitestarGroup, name="assets")
+def vite_group() -> None:
+    """Manage Vite Tasks."""
+
+
+@vite_group.command(
+    name="init",
+    help="Initialize vite for your project.",
+)
+@option(
+    "--root-path",
+    type=ClickPath(dir_okay=True, file_okay=False, path_type=Path),
+    help="The path for the initial the Vite application.  This is the equivalent to the top-level folder in a normal Vue or React application..",
+    default=None,
+    required=False,
+)
+@option(
+    "--bundle-path",
+    type=ClickPath(dir_okay=True, file_okay=False, path_type=Path),
+    help="The path for the built Vite assets.  This is the where the output of `npm run build` will write files.",
+    default=None,
+    required=False,
+)
+@option(
+    "--resource-path",
+    type=ClickPath(dir_okay=True, file_okay=False, path_type=Path),
+    help="The path to your Javascript/Typescript source and associated assets.  If this were a standalone Vue or React app, this would point to your `src/` folder.",
+    default=None,
+    required=False,
+)
+@option(
+    "--public-path",
+    type=ClickPath(dir_okay=True, file_okay=False, path_type=Path),
+    help="The optional path to your public/static JS assets.  If this were a standalone Vue or React app, this would point to your `public/` folder.",
+    default=None,
+    required=False,
+)
+@option("--asset-url", type=str, help="Base url to serve assets from.", default=None, required=False)
+@option(
+    "--vite-port",
+    type=int,
+    help="The port to run the vite server against.",
+    default=None,
+    is_flag=True,
+    required=False,
+)
+@option(
+    "--enable-ssr",
+    type=bool,
+    help="Enable SSR Support.",
+    required=False,
+    show_default=False,
+    is_flag=True,
+)
+@option("--overwrite", type=bool, help="Overwrite any files in place.", default=False, is_flag=True)
+@option("--verbose", type=bool, help="Enable verbose output.", default=False, is_flag=True)
+@option(
+    "--no-prompt",
+    help="Do not prompt for confirmation and use all defaults for initializing the project.",
+    type=bool,
+    default=False,
+    required=False,
+    show_default=True,
+    is_flag=True,
+)
+@option(
+    "--no-install",
+    help="Do not execute the installation commands after generating templates.",
+    type=bool,
+    default=False,
+    required=False,
+    show_default=True,
+    is_flag=True,
+)
+def vite_init(
+    ctx: Context,
+    vite_port: int | None,
+    enable_ssr: bool | None,
+    asset_url: str | None,
+    root_path: Path | None,
+    bundle_path: Path | None,
+    resource_path: Path | None,
+    public_path: Path | None,
+    overwrite: bool,
+    verbose: bool,
+    no_prompt: bool,
+    no_install: bool,
+) -> None:  # sourcery skip: low-code-quality
+    """Run vite build."""
+    import os
+    import sys
+    from importlib.util import find_spec
+    from pathlib import Path
+
+    from litestar.cli._utils import (
+        console,
+    )
+    from rich.prompt import Confirm
+
+    from litestar_vite import VitePlugin
+    from litestar_vite.commands import execute_command, init_vite
+
+    if callable(ctx.obj):
+        ctx.obj = ctx.obj()
+    elif verbose:
+        ctx.obj.app.debug = True
+    env: LitestarEnv = ctx.obj
+    plugin = env.app.plugins.get(VitePlugin)
+    config = plugin._config  # pyright: ignore[reportPrivateUsage]
+
+    console.rule("[yellow]Initializing Vite[/]", align="left")
+    root_path = Path(root_path or config.root_dir or Path.cwd())
+    resource_path = Path(resource_path or config.resource_dir)
+    public_path = Path(public_path or config.public_dir)
+    bundle_path = Path(bundle_path or config.bundle_dir)
+    enable_ssr = enable_ssr or config.ssr_enabled
+    asset_url = asset_url or config.asset_url
+    vite_port = vite_port or config.port
+    hot_file = Path(bundle_path / config.hot_file)
+
+    if any(output_path.exists() for output_path in (bundle_path, resource_path)) and not any(
+        [overwrite, no_prompt],
+    ):
+        confirm_overwrite = Confirm.ask(
+            "Files were found in the paths specified.  Are you sure you wish to overwrite the contents?",
+        )
+        if not confirm_overwrite:
+            console.print("Skipping Vite initialization")
+            sys.exit(2)
+
+    enable_ssr = (
+        True
+        if enable_ssr
+        else False
+        if no_prompt
+        else Confirm.ask(
+            "Do you intend to use Litestar with any SSR framework?",
+        )
+    )
+    init_vite(
+        app=env.app,
+        root_path=root_path,
+        enable_ssr=enable_ssr,
+        vite_port=vite_port,
+        asset_url=asset_url,
+        resource_path=resource_path,
+        public_path=public_path,
+        bundle_path=bundle_path,
+        hot_file=hot_file,
+        litestar_port=env.port or 8000,
+    )
+    if not no_install:
+        if find_spec("nodeenv") is not None and plugin.config.detect_nodeenv:
+            """Detect nodeenv installed in the current python env before using a global version"""
+            nodeenv_command = (
+                str(Path(Path(sys.executable) / "nodeenv"))
+                if Path(Path(sys.executable) / "nodeenv").exists()
+                else "nodeenv"
+            )
+            install_dir = os.environ.get("VIRTUAL_ENV", sys.prefix)
+            console.rule("[yellow]Starting Nodeenv installation process[/]", align="left")
+            console.print(f"Installing Node environment into {install_dir}")
+            execute_command(command_to_run=[nodeenv_command, install_dir, "--force", "--quiet"], cwd=root_path)
+
+        console.rule("[yellow]Starting package installation process[/]", align="left")
+
+        execute_command(command_to_run=plugin.config.install_command, cwd=root_path)
+
+
+@vite_group.command(
+    name="install",
+    help="Install frontend packages.",
+)
+@option("--verbose", type=bool, help="Enable verbose output.", default=False, is_flag=True)
+def vite_install(app: Litestar, verbose: bool) -> None:
+    """Run vite build."""
+    import os
+    import sys
+    from importlib.util import find_spec
+    from pathlib import Path
+
+    from litestar.cli._utils import console
+
+    from litestar_vite.commands import execute_command
+    from litestar_vite.plugin import VitePlugin
+
+    if verbose:
+        app.debug = True
+    plugin = app.plugins.get(VitePlugin)
+
+    if find_spec("nodeenv") is not None and plugin.config.detect_nodeenv:
+        """Detect nodeenv installed in the current python env before using a global version"""
+        nodeenv_command = (
+            str(Path(Path(sys.executable) / "nodeenv"))
+            if Path(Path(sys.executable) / "nodeenv").exists()
+            else "nodeenv"
+        )
+        install_dir = os.environ.get("VIRTUAL_ENV", sys.prefix)
+        console.rule("[yellow]Starting Nodeenv installation process[/]", align="left")
+        console.print("Installing Node environment to %s:", install_dir)
+        execute_command(command_to_run=[nodeenv_command, install_dir, "--force", "--quiet"], cwd=plugin.config.root_dir)
+
+    console.rule("[yellow]Starting package installation process[/]", align="left")
+
+    execute_command(command_to_run=plugin.config.install_command, cwd=plugin.config.root_dir)
+
+
+@vite_group.command(
+    name="build",
+    help="Building frontend assets with Vite.",
+)
+@option("--verbose", type=bool, help="Enable verbose output.", default=False, is_flag=True)
+def vite_build(app: Litestar, verbose: bool) -> None:
+    """Run vite build."""
+    from litestar.cli._utils import (
+        console,
+    )
+
+    from litestar_vite.commands import execute_command
+    from litestar_vite.plugin import VitePlugin, set_environment
+
+    if verbose:
+        app.debug = True
+    console.rule("[yellow]Starting Vite build process[/]", align="left")
+    plugin = app.plugins.get(VitePlugin)
+    if plugin.config.set_environment:
+        set_environment(config=plugin.config)
+    p = execute_command(command_to_run=plugin.config.build_command, cwd=plugin.config.root_dir)
+    if p.returncode == 0:
+        console.print("[bold green] Assets built.[/]")
+    else:
+        console.print("[bold red] There was an error building the assets.[/]")
+
+
+@vite_group.command(
+    name="serve",
+    help="Serving frontend assets with Vite.",
+)
+@option("--verbose", type=bool, help="Enable verbose output.", default=False, is_flag=True)
+def vite_serve(app: Litestar, verbose: bool) -> None:
+    """Run vite serve."""
+    from litestar.cli._utils import (
+        console,
+    )
+
+    from litestar_vite.commands import execute_command
+    from litestar_vite.plugin import VitePlugin, set_environment
+
+    if verbose:
+        app.debug = True
+
+    plugin = app.plugins.get(VitePlugin)
+    if plugin.config.set_environment:
+        set_environment(config=plugin.config)
+    if plugin.config.hot_reload:
+        console.rule("[yellow]Starting Vite process with HMR Enabled[/]", align="left")
+    else:
+        console.rule("[yellow]Starting Vite watch and build process[/]", align="left")
+    command_to_run = plugin.config.run_command if plugin.config.hot_reload else plugin.config.build_watch_command
+    execute_command(command_to_run=command_to_run, cwd=plugin.config.root_dir)
+    console.print("[yellow]Vite process stopped.[/]")
+
+
+@vite_group.command(
+    name="generate-routes",
+    help="Generate a JSON file with the route configuration",
+)
+@option(
+    "--output",
+    help="output file path",
+    type=ClickPath(dir_okay=False, path_type=Path),
+    default=Path("routes.json"),
+    show_default=True,
+)
+@option("--verbose", type=bool, help="Enable verbose output.", default=False, is_flag=True)
+def generate_js_routes(app: Litestar, output: Path, verbose: bool) -> None:
+    """Run vite serve."""
+    import msgspec
+    from litestar.cli._utils import (
+        LitestarCLIException,
+        console,
+    )
+    from litestar.serialization import encode_json, get_serializer
+
+    from litestar_vite.plugin import VitePlugin, set_environment
+
+    if verbose:
+        app.debug = True
+    serializer = get_serializer(app.type_encoders)
+    plugin = app.plugins.get(VitePlugin)
+    if plugin.config.set_environment:
+        set_environment(config=plugin.config)
+    content = msgspec.json.format(
+        encode_json(app.openapi_schema.to_schema(), serializer=serializer),
+        indent=4,
+    )
+
+    try:
+        output.write_bytes(content)
+    except OSError as e:  # pragma: no cover
+        msg = f"failed to write schema to path {output}"
+        raise LitestarCLIException(msg) from e
+
+    console.print("[yellow]Vite process stopped.[/]")

litestar_vite/commands.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+import platform
+import subprocess
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, MutableMapping
+
+if TYPE_CHECKING:
+    from jinja2 import Environment, Template
+    from litestar import Litestar
+
+VITE_INIT_TEMPLATES: set[str] = {"package.json.j2", "tsconfig.json.j2", "vite.config.ts.j2"}
+DEFAULT_RESOURCES: set[str] = {"styles.css.j2", "main.ts.j2"}
+DEFAULT_DEV_DEPENDENCIES: dict[str, str] = {
+    "typescript": "^5.7.2",
+    "vite": "^6.0.6",
+    "litestar-vite-plugin": "^0.13.0",
+    "@types/node": "^22.10.2",
+}
+DEFAULT_DEPENDENCIES: dict[str, str] = {"axios": "^1.7.9"}
+
+
+def to_json(value: Any) -> str:
+    """Serialize JSON field values.
+
+    Args:
+        value: Any json serializable value.
+
+    Returns:
+        JSON string.
+    """
+    from litestar.serialization import encode_json
+
+    return encode_json(value).decode("utf-8")
+
+
+def init_vite(
+    app: Litestar,
+    root_path: Path,
+    resource_path: Path,
+    asset_url: str,
+    public_path: Path,
+    bundle_path: Path,
+    enable_ssr: bool,
+    vite_port: int,
+    hot_file: Path,
+    litestar_port: int,
+) -> None:
+    """Initialize a new Vite project.
+
+    Args:
+        app: The Litestar application instance.
+        root_path: Root directory for the Vite project.
+        resource_path: Directory containing source files.
+        asset_url: Base URL for serving assets.
+        public_path: Directory for static files.
+        bundle_path: Output directory for built files.
+        enable_ssr: Enable server-side rendering.
+        vite_port: Port for Vite dev server.
+        hot_file: Path to hot reload manifest.
+        litestar_port: Port for Litestar server.
+    """
+    from jinja2 import Environment, FileSystemLoader, select_autoescape
+    from litestar.cli._utils import console
+    from litestar.utils import module_loader
+
+    template_path = module_loader.module_to_os_path("litestar_vite.templates")
+    vite_template_env = Environment(
+        loader=FileSystemLoader([template_path]),
+        autoescape=select_autoescape(),
+    )
+
+    enabled_templates: set[str] = VITE_INIT_TEMPLATES
+    enabled_resources: set[str] = DEFAULT_RESOURCES
+    dependencies: dict[str, str] = DEFAULT_DEPENDENCIES
+    dev_dependencies: dict[str, str] = DEFAULT_DEV_DEPENDENCIES
+    templates: dict[str, Template] = {
+        template_name: get_template(environment=vite_template_env, name=template_name)
+        for template_name in enabled_templates
+    }
+
+    # Prepare root_path
+    root_path.mkdir(parents=True, exist_ok=True)
+    for template_name, template in templates.items():
+        target_file_name = template_name[:-3] if template_name.endswith(".j2") else template_name
+        target_file_path = root_path / target_file_name
+        with target_file_path.open(mode="w") as file:
+            console.print(f" * Writing {target_file_name} to {target_file_path!s}")
+
+            file.write(
+                template.render(
+                    entry_point=[
+                        f"{resource_path!s}/{resource_name[:-3] if resource_name.endswith('.j2') else resource_name}"
+                        for resource_name in enabled_resources
+                    ],
+                    enable_ssr=enable_ssr,
+                    asset_url=asset_url,
+                    root_path=root_path,
+                    resource_path=str(resource_path),
+                    public_path=str(public_path),
+                    bundle_path=str(bundle_path),
+                    hot_file=str(hot_file),
+                    vite_port=str(vite_port),
+                    litestar_port=litestar_port,
+                    dependencies=to_json(dependencies),
+                    dev_dependencies=to_json(dev_dependencies),
+                ),
+            )
+
+    (root_path / bundle_path).mkdir(parents=True, exist_ok=True)
+    (root_path / public_path).mkdir(parents=True, exist_ok=True)
+    (root_path / resource_path).mkdir(parents=True, exist_ok=True)
+    for resource_name in enabled_resources:
+        template = get_template(environment=vite_template_env, name=resource_name)
+        target_file_name = f"{resource_name[:-3] if resource_name.endswith('.j2') else resource_name}"
+        target_file_path = root_path / resource_path / target_file_name
+        with target_file_path.open(mode="w") as file:
+            console.print(
+                f" * Writing {resource_name[:-3] if resource_name.endswith('.j2') else resource_name} to {target_file_path!s}",
+            )
+            file.write(template.render())
+    console.print("[yellow]Vite initialization completed.[/]")
+
+
+def get_template(
+    environment: Environment,
+    name: str | Template,
+    parent: str | None = None,
+    globals: MutableMapping[str, Any] | None = None,  # noqa: A002
+) -> Template:
+    return environment.get_template(name=name, parent=parent, globals=globals)
+
+
+def execute_command(command_to_run: list[str], cwd: str | Path | None = None) -> subprocess.CompletedProcess[bytes]:
+    """Run Vite in a subprocess."""
+    kwargs = {}
+    if cwd is not None:
+        kwargs["cwd"] = Path(cwd)
+    return subprocess.run(command_to_run, check=False, shell=platform.system() == "Windows", **kwargs)  # type: ignore[call-overload]

litestar_vite/config.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+__all__ = ("ViteConfig",)
+TRUE_VALUES = {"True", "true", "1", "yes", "Y", "T"}
+
+
+@dataclass
+class ViteConfig:
+    """Configuration for ViteJS support.
+
+    To enable Vite integration, pass an instance of this class to the
+    :class:`Litestar <litestar.app.Litestar>` constructor using the
+    'plugins' key.
+    """
+
+    bundle_dir: Path | str = field(default="public")
+    """Location of the compiled assets from  Vite.
+
+    The manifest file will also be found here.
+    """
+    resource_dir: Path | str = field(default="resources")
+    """The directory where all typescript/javascript source are written.
+
+    In a standalone Vue or React application, this would be equivalent to the ``./src`` directory.
+    """
+    public_dir: Path | str = field(default="public")
+    """The optional public directory Vite serves assets from.
+
+    In a standalone Vue or React application, this would be equivalent to the ``./public`` directory.
+    """
+    manifest_name: str = "manifest.json"
+    """Name of the manifest file."""
+    hot_file: str = "hot"
+    """Name of the hot file.
+
+    This file contains a single line containing the host, protocol, and port the Vite server is running.
+    """
+    hot_reload: bool = field(
+        default_factory=lambda: os.getenv("VITE_HOT_RELOAD", "True") in TRUE_VALUES,
+    )
+    """Enable HMR for Vite development server."""
+    ssr_enabled: bool = False
+    """Enable SSR."""
+    ssr_output_dir: Path | str | None = None
+    """SSR Output path"""
+    root_dir: Path | str | None = None
+    """The is the base path to your application.
+
+   In a standalone Vue or React application, this would be equivalent to the top-level project folder containing the ``./src`` directory.
+
+    """
+    is_react: bool = False
+    """Enable React components."""
+    asset_url: str = field(default_factory=lambda: os.getenv("ASSET_URL", "/static/"))
+    """Base URL to generate for static asset references.
+
+    This URL will be prepended to anything generated from Vite.
+    """
+    host: str = field(default_factory=lambda: os.getenv("VITE_HOST", "localhost"))
+    """Default host to use for Vite server."""
+    protocol: str = "http"
+    """Protocol to use for communication"""
+    port: int = field(default_factory=lambda: int(os.getenv("VITE_PORT", "5173")))
+    """Default port to use for Vite server."""
+    run_command: list[str] = field(default_factory=lambda: ["npm", "run", "dev"])
+    """Default command to use for running Vite."""
+    build_watch_command: list[str] = field(default_factory=lambda: ["npm", "run", "watch"])
+    """Default command to use for dev building with Vite."""
+    build_command: list[str] = field(default_factory=lambda: ["npm", "run", "build"])
+    """Default command to use for building with Vite."""
+    install_command: list[str] = field(default_factory=lambda: ["npm", "install"])
+    """Default command to use for installing Vite."""
+    use_server_lifespan: bool = field(
+        default_factory=lambda: os.getenv("VITE_USE_SERVER_LIFESPAN", "False") in TRUE_VALUES,
+    )
+    """Utilize the server lifespan hook to run Vite."""
+    dev_mode: bool = field(
+        default_factory=lambda: os.getenv("VITE_DEV_MODE", "False") in TRUE_VALUES,
+    )
+    """When True, Vite will run with HMR or watch build"""
+    detect_nodeenv: bool = True
+    """When True, The initializer will install and configure nodeenv if present"""
+    set_environment: bool = True
+    """When True, configuration in this class will be set into environment variables.
+
+    This can be useful to ensure Vite always uses the configuration supplied to the plugin
+    """
+    set_static_folders: bool = True
+    """When True, Litestar will automatically serve assets at the `ASSET_URL` path.
+    """
+
+    def __post_init__(self) -> None:
+        """Ensure that directory is set if engine is a class."""
+        if self.root_dir is not None and isinstance(self.root_dir, str):
+            self.root_dir = Path(self.root_dir)
+        elif self.root_dir is None:
+            self.root_dir = Path()
+        if self.public_dir and isinstance(self.public_dir, str):
+            self.public_dir = Path(self.public_dir)
+        if isinstance(self.resource_dir, str):
+            self.resource_dir = Path(self.resource_dir)
+        if isinstance(self.bundle_dir, str):
+            self.bundle_dir = Path(self.bundle_dir)
+        if isinstance(self.ssr_output_dir, str):
+            self.ssr_output_dir = Path(self.ssr_output_dir)

litestar_vite/inertia/__init__.py

@@ -0,0 +1,37 @@
+from litestar_vite.inertia import helpers
+from litestar_vite.inertia.config import InertiaConfig
+from litestar_vite.inertia.exception_handler import create_inertia_exception_response, exception_to_http_response
+from litestar_vite.inertia.helpers import error, get_shared_props, js_routes_script, lazy, share
+from litestar_vite.inertia.middleware import InertiaMiddleware
+from litestar_vite.inertia.plugin import InertiaPlugin
+from litestar_vite.inertia.request import InertiaDetails, InertiaHeaders, InertiaRequest
+from litestar_vite.inertia.response import (
+    InertiaBack,
+    InertiaExternalRedirect,
+    InertiaRedirect,
+    InertiaResponse,
+)
+
+from .routes import generate_js_routes
+
+__all__ = (
+    "InertiaBack",
+    "InertiaConfig",
+    "InertiaDetails",
+    "InertiaExternalRedirect",
+    "InertiaHeaders",
+    "InertiaMiddleware",
+    "InertiaPlugin",
+    "InertiaRedirect",
+    "InertiaRequest",
+    "InertiaResponse",
+    "create_inertia_exception_response",
+    "error",
+    "exception_to_http_response",
+    "generate_js_routes",
+    "get_shared_props",
+    "helpers",
+    "js_routes_script",
+    "lazy",
+    "share",
+)