litestar-vite 0.1.1__py3-none-any.whl → 0.15.0__py3-none-any.whl

litestar_vite/scaffolding/generator.py

@@ -0,0 +1,270 @@
+"""Project scaffolding generator.
+
+This module handles the generation of project files from templates.
+"""
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from litestar_vite.scaffolding.templates import FrameworkTemplate
+
+
+def _dict_factory() -> dict[str, Any]:
+    return {}
+
+
+_DictStrAnyFactory: Callable[[], dict[str, Any]] = _dict_factory
+
+
+@dataclass
+class TemplateContext:
+    """Context variables for template rendering.
+
+    Attributes:
+        project_name: Name of the project
+        framework: The selected framework template
+        use_typescript: Whether to use TypeScript
+        use_tailwind: Whether to add TailwindCSS
+        vite_port: Vite dev server port
+        litestar_port: Litestar server port
+        asset_url: Base URL for assets
+        resource_dir: Source directory for frontend files
+        bundle_dir: Output directory for built files
+        enable_ssr: Whether SSR is enabled
+        enable_inertia: Whether Inertia.js is used
+        enable_types: Whether type generation is enabled
+        generate_zod: Whether to generate Zod schemas
+        generate_client: Whether to generate API client
+    """
+
+    project_name: str
+    framework: "FrameworkTemplate"
+    use_typescript: bool = True
+    use_tailwind: bool = False
+    vite_port: int = 5173
+    litestar_port: int = 8000
+    asset_url: str = "/static/"
+    resource_dir: str = "resources"
+    bundle_dir: str = "public"
+    static_dir: str = "public"
+    base_dir: str = "."
+    enable_ssr: bool = False
+    enable_inertia: bool = False
+    enable_types: bool = True
+    generate_zod: bool = False
+    generate_client: bool = False
+    extra: dict[str, Any] = field(default_factory=_DictStrAnyFactory)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert context to dictionary for Jinja2 rendering.
+
+        Returns:
+            Dictionary of template variables.
+        """
+        return {
+            "project_name": self.project_name,
+            "framework": self.framework.type.value,
+            "framework_name": self.framework.name,
+            "use_typescript": self.use_typescript,
+            "use_tailwind": self.use_tailwind,
+            "vite_port": self.vite_port,
+            "litestar_port": self.litestar_port,
+            "asset_url": self.asset_url,
+            "resource_dir": self.resource_dir,
+            "bundle_dir": self.bundle_dir,
+            "static_dir": self.static_dir,
+            "base_dir": self.base_dir,
+            "enable_ssr": self.enable_ssr,
+            "enable_inertia": self.enable_inertia,
+            "enable_types": self.enable_types,
+            "generate_zod": self.generate_zod,
+            "generate_client": self.generate_client,
+            "dependencies": self.framework.dependencies,
+            "dev_dependencies": self.framework.dev_dependencies,
+            "vite_plugin": self.framework.vite_plugin,
+            "uses_vite": self.framework.uses_vite,
+            **self.extra,
+        }
+
+
+def get_template_dir() -> Path:
+    """Get the directory containing framework templates.
+
+    Returns:
+        Path to the templates directory.
+    """
+    return Path(__file__).parent.parent / "templates"
+
+
+def render_template(template_path: Path, context: dict[str, Any]) -> str:
+    """Render a Jinja2 template with the given context.
+
+    Templates are rendered with autoescaping disabled because the output is code
+    and configuration files, not HTML.
+
+    Args:
+        template_path: Path to the template file.
+        context: Dictionary of template variables.
+
+    Returns:
+        Rendered template content.
+    """
+    from jinja2 import Environment, FileSystemLoader
+
+    template_dir = template_path.parent
+    env = Environment(
+        loader=FileSystemLoader(str(template_dir)),
+        keep_trailing_newline=True,
+        autoescape=False,  # noqa: S701
+    )
+    template = env.get_template(template_path.name)
+    return template.render(**context)
+
+
+def _process_templates(
+    template_dir: Path,
+    output_dir: Path,
+    context_dict: dict[str, Any],
+    resource_dir: str,
+    *,
+    overwrite: bool,
+    skip_paths: "set[Path] | None" = None,
+) -> list[Path]:
+    """Process templates from a directory and generate output files.
+
+    This function rewrites template paths so frameworks can customize the output
+    directory layout:
+
+    - ``resources/`` templates are rewritten to the configured ``resource_dir``.
+    - ``public/`` templates can be relocated via ``static_dir`` in the context.
+
+    SSR entrypoints under ``resources/`` are only generated when SSR is enabled.
+
+    Args:
+        template_dir: Directory containing template files.
+        output_dir: Directory to write generated files.
+        context_dict: Template context dictionary.
+        resource_dir: Resource directory name for path rewriting.
+        overwrite: Whether to overwrite existing files.
+        skip_paths: Set of relative paths to skip.
+
+    Returns:
+        List of generated file paths.
+    """
+    from litestar.cli._utils import console  # pyright: ignore[reportPrivateImportUsage]
+
+    generated_files: list[Path] = []
+    skip_paths = skip_paths or set()
+    enable_ssr = bool(context_dict.get("enable_ssr"))
+
+    for template_file in template_dir.glob("**/*.j2"):
+        relative_path = template_file.relative_to(template_dir)
+
+        if relative_path in skip_paths:
+            continue
+
+        if (
+            not enable_ssr
+            and relative_path.parts
+            and relative_path.parts[0] == "resources"
+            and relative_path.name.startswith("ssr.")
+        ):
+            continue
+
+        if relative_path.parts and relative_path.parts[0] == "resources":
+            relative_path = Path(resource_dir, *relative_path.parts[1:])
+
+        if relative_path.parts and relative_path.parts[0] == "public":
+            relative_path = Path(context_dict.get("static_dir", "public"), *relative_path.parts[1:])
+
+        output_path = output_dir / str(relative_path).replace(".j2", "")
+
+        if output_path.exists() and not overwrite:
+            console.print(f"[yellow]Skipping {output_path} (exists)[/]")
+            continue
+
+        _render_and_write(template_file, output_path, context_dict)
+        generated_files.append(output_path)
+
+    return generated_files
+
+
+def generate_project(output_dir: Path, context: TemplateContext, *, overwrite: bool = False) -> list[Path]:
+    """Generate project files from templates.
+
+    Args:
+        output_dir: Directory to generate files in.
+        context: Template context with configuration.
+        overwrite: Whether to overwrite existing files.
+
+    Returns:
+        List of generated file paths.
+    """
+    from litestar.cli._utils import console  # pyright: ignore[reportPrivateImportUsage]
+
+    template_dir = get_template_dir()
+    framework_dir = template_dir / context.framework.type.value
+    base_dir = template_dir / "base"
+    context_dict = context.to_dict()
+    generated_files: list[Path] = []
+
+    framework_overrides: set[Path] = set()
+    if framework_dir.exists():
+        framework_overrides = {
+            template_file.relative_to(framework_dir) for template_file in framework_dir.glob("**/*.j2")
+        }
+
+    actual_output_dir = output_dir / context.base_dir if context.base_dir not in {"", "."} else output_dir
+    actual_output_dir.mkdir(parents=True, exist_ok=True)
+
+    if context.framework.uses_vite and base_dir.exists():
+        generated_files.extend(
+            _process_templates(
+                base_dir,
+                actual_output_dir,
+                context_dict,
+                context.resource_dir,
+                overwrite=overwrite,
+                skip_paths=framework_overrides,
+            )
+        )
+
+    if framework_dir.exists():
+        generated_files.extend(
+            _process_templates(
+                framework_dir, actual_output_dir, context_dict, context.resource_dir, overwrite=overwrite
+            )
+        )
+    else:
+        console.print(f"[dim]No framework templates for {context.framework.type.value}, using base templates[/]")
+
+    if context.use_tailwind:
+        tailwind_dir = template_dir / "addons" / "tailwindcss"
+        if tailwind_dir.exists():
+            generated_files.extend(
+                _process_templates(
+                    tailwind_dir, actual_output_dir, context_dict, context.resource_dir, overwrite=overwrite
+                )
+            )
+
+    return generated_files
+
+
+def _render_and_write(template_path: Path, output_path: Path, context: dict[str, Any]) -> None:
+    """Render a template and write to output file.
+
+    Args:
+        template_path: Path to the template file.
+        output_path: Path to write the rendered content.
+        context: Template context dictionary.
+    """
+    from litestar.cli._utils import console  # pyright: ignore[reportPrivateImportUsage]
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    content = render_template(template_path, context)
+    output_path.write_text(content, encoding="utf-8")
+    console.print(f"[green]Created {output_path}[/]")

litestar_vite/scaffolding/templates.py

@@ -0,0 +1,437 @@
+"""Framework template definitions for scaffolding.
+
+This module defines the available framework templates and their configurations.
+"""
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+def _str_list_factory() -> list[str]:
+    return []
+
+
+class FrameworkType(str, Enum):
+    """Supported frontend framework types."""
+
+    REACT = "react"
+    REACT_ROUTER = "react-router"
+    REACT_TANSTACK = "react-tanstack"
+    REACT_INERTIA = "react-inertia"
+    VUE = "vue"
+    VUE_INERTIA = "vue-inertia"
+    SVELTE = "svelte"
+    SVELTE_INERTIA = "svelte-inertia"
+    SVELTEKIT = "sveltekit"
+    NUXT = "nuxt"
+    ASTRO = "astro"
+    HTMX = "htmx"
+    ANGULAR = "angular"
+    ANGULAR_CLI = "angular-cli"
+
+
+_ListStrFactory: Callable[[], list[str]] = _str_list_factory
+
+
+@dataclass
+class FrameworkTemplate:
+    """Configuration for a frontend framework template.
+
+    Attributes:
+        name: Display name for the template
+        type: Framework type enum
+        description: Brief description shown in selection UI
+        vite_plugin: Name of the Vite plugin import (if any)
+        dependencies: NPM dependencies to install
+        dev_dependencies: NPM dev dependencies to install
+        files: List of template files to generate
+        uses_typescript: Whether TypeScript is used by default
+        has_ssr: Whether SSR is supported
+        inertia_compatible: Whether it works with Inertia.js
+        uses_vite: Whether the template is Vite-based (skip base files when False)
+        resource_dir: Preferred source directory name for the framework
+    """
+
+    name: str
+    type: FrameworkType
+    description: str
+    vite_plugin: "str | None" = None
+    dependencies: list[str] = field(default_factory=_ListStrFactory)
+    dev_dependencies: list[str] = field(default_factory=_ListStrFactory)
+    files: list[str] = field(default_factory=_ListStrFactory)
+    uses_typescript: bool = True
+    has_ssr: bool = False
+    inertia_compatible: bool = False
+    uses_vite: bool = True
+    resource_dir: str = "resources"
+
+
+FRAMEWORK_TEMPLATES: dict[FrameworkType, FrameworkTemplate] = {
+    FrameworkType.REACT: FrameworkTemplate(
+        name="React",
+        type=FrameworkType.REACT,
+        description="React 18+ with TypeScript and Vite",
+        vite_plugin="@vitejs/plugin-react",
+        dependencies=["react", "react-dom"],
+        dev_dependencies=["@vitejs/plugin-react", "@types/react", "@types/react-dom", "typescript"],
+        files=[
+            "vite.config.ts",
+            "tsconfig.json",
+            "package.json",
+            "index.html",
+            "src/main.tsx",
+            "src/App.tsx",
+            "src/App.css",
+        ],
+        uses_typescript=True,
+        has_ssr=False,
+        inertia_compatible=True,
+        resource_dir="src",
+    ),
+    FrameworkType.REACT_ROUTER: FrameworkTemplate(
+        name="React + React Router",
+        type=FrameworkType.REACT_ROUTER,
+        description="React 18+ with React Router for SPA routing",
+        vite_plugin="@vitejs/plugin-react",
+        dependencies=["react", "react-dom", "react-router-dom"],
+        dev_dependencies=["@vitejs/plugin-react", "@types/react", "@types/react-dom", "typescript"],
+        files=[
+            "vite.config.ts",
+            "tsconfig.json",
+            "package.json",
+            "index.html",
+            "src/main.tsx",
+            "src/App.tsx",
+            "src/App.css",
+        ],
+        uses_typescript=True,
+        has_ssr=False,
+        inertia_compatible=False,
+        resource_dir="src",
+    ),
+    FrameworkType.REACT_TANSTACK: FrameworkTemplate(
+        name="React + TanStack Router",
+        type=FrameworkType.REACT_TANSTACK,
+        description="React 18+ with TanStack Router (file-based), Zod, and API client",
+        vite_plugin="@vitejs/plugin-react",
+        dependencies=["react", "react-dom", "@tanstack/react-router", "zod"],
+        dev_dependencies=[
+            "@vitejs/plugin-react",
+            "@tanstack/router-plugin",
+            "@hey-api/openapi-ts",
+            "@types/react",
+            "@types/react-dom",
+            "typescript",
+        ],
+        files=[
+            "vite.config.ts",
+            "tsconfig.json",
+            "package.json",
+            "index.html",
+            "src/main.tsx",
+            "src/routes/__root.tsx",
+            "src/routes/index.tsx",
+            "src/routes/books.tsx",
+            "src/routeTree.gen.ts",
+            "src/App.css",
+            "openapi-ts.config.ts",
+        ],
+        uses_typescript=True,
+        has_ssr=False,
+        inertia_compatible=False,
+        resource_dir="src",
+    ),
+    FrameworkType.REACT_INERTIA: FrameworkTemplate(
+        name="React + Inertia.js",
+        type=FrameworkType.REACT_INERTIA,
+        description="React 18+ with Inertia.js for server-side routing",
+        vite_plugin="@vitejs/plugin-react",
+        dependencies=["react", "react-dom", "@inertiajs/react"],
+        dev_dependencies=["@vitejs/plugin-react", "@types/react", "@types/react-dom", "typescript", "vite"],
+        files=[
+            "vite.config.ts",
+            "tsconfig.json",
+            "package.json",
+            "index.html",
+            "resources/main.tsx",
+            "resources/ssr.tsx",
+            "resources/pages/Home.tsx",
+            "resources/App.css",
+        ],
+        uses_typescript=True,
+        has_ssr=True,
+        inertia_compatible=True,
+        resource_dir="resources",
+    ),
+    FrameworkType.VUE: FrameworkTemplate(
+        name="Vue 3",
+        type=FrameworkType.VUE,
+        description="Vue 3 with Composition API and TypeScript",
+        vite_plugin="@vitejs/plugin-vue",
+        dependencies=["vue"],
+        dev_dependencies=["@vitejs/plugin-vue", "vue-tsc", "typescript"],
+        files=[
+            "vite.config.ts",
+            "tsconfig.json",
+            "package.json",
+            "index.html",
+            "env.d.ts",
+            "src/main.ts",
+            "src/App.vue",
+            "src/style.css",
+        ],
+        uses_typescript=True,
+        has_ssr=False,
+        inertia_compatible=True,
+        resource_dir="src",
+    ),
+    FrameworkType.VUE_INERTIA: FrameworkTemplate(
+        name="Vue + Inertia.js",
+        type=FrameworkType.VUE_INERTIA,
+        description="Vue 3 with Inertia.js for server-side routing",
+        vite_plugin="@vitejs/plugin-vue",
+        dependencies=["vue", "@inertiajs/vue3"],
+        dev_dependencies=["@vitejs/plugin-vue", "vue-tsc", "typescript"],
+        files=[
+            "vite.config.ts",
+            "tsconfig.json",
+            "package.json",
+            "index.html",
+            "env.d.ts",
+            "resources/main.ts",
+            "resources/ssr.ts",
+            "resources/pages/Home.vue",
+            "resources/style.css",
+        ],
+        uses_typescript=True,
+        has_ssr=True,
+        inertia_compatible=True,
+        resource_dir="resources",
+    ),
+    FrameworkType.SVELTE: FrameworkTemplate(
+        name="Svelte 5",
+        type=FrameworkType.SVELTE,
+        description="Svelte 5 with runes and TypeScript",
+        vite_plugin="@sveltejs/vite-plugin-svelte",
+        dependencies=["svelte"],
+        dev_dependencies=["@sveltejs/vite-plugin-svelte", "svelte-check", "typescript", "tslib"],
+        files=[
+            "vite.config.ts",
+            "svelte.config.js",
+            "tsconfig.json",
+            "package.json",
+            "index.html",
+            "src/main.ts",
+            "src/App.svelte",
+            "src/app.css",
+        ],
+        uses_typescript=True,
+        has_ssr=False,
+        inertia_compatible=True,
+        resource_dir="src",
+    ),
+    FrameworkType.SVELTE_INERTIA: FrameworkTemplate(
+        name="Svelte + Inertia.js",
+        type=FrameworkType.SVELTE_INERTIA,
+        description="Svelte 5 with Inertia.js for server-side routing",
+        vite_plugin="@sveltejs/vite-plugin-svelte",
+        dependencies=["svelte", "@inertiajs/svelte"],
+        dev_dependencies=["@sveltejs/vite-plugin-svelte", "svelte-check", "typescript", "tslib"],
+        files=[
+            "vite.config.ts",
+            "svelte.config.js",
+            "tsconfig.json",
+            "package.json",
+            "index.html",
+            "resources/main.ts",
+            "resources/pages/Home.svelte",
+            "resources/app.css",
+        ],
+        uses_typescript=True,
+        has_ssr=False,
+        inertia_compatible=True,
+        resource_dir="resources",
+    ),
+    FrameworkType.SVELTEKIT: FrameworkTemplate(
+        name="SvelteKit",
+        type=FrameworkType.SVELTEKIT,
+        description="SvelteKit with Litestar API backend",
+        vite_plugin="litestar-vite-plugin/sveltekit",
+        dependencies=["svelte", "@sveltejs/kit"],
+        dev_dependencies=[
+            "@sveltejs/vite-plugin-svelte",
+            "@sveltejs/adapter-auto",
+            "svelte-check",
+            "typescript",
+            "tslib",
+            "litestar-vite-plugin",
+        ],
+        files=[
+            "vite.config.ts",
+            "svelte.config.js",
+            "tsconfig.json",
+            "src/app.html",
+            "src/app.css",
+            "src/hooks.server.ts",
+            "src/routes/+page.svelte",
+            "src/routes/+layout.svelte",
+        ],
+        uses_typescript=True,
+        has_ssr=True,
+        inertia_compatible=False,
+    ),
+    FrameworkType.NUXT: FrameworkTemplate(
+        name="Nuxt 3",
+        type=FrameworkType.NUXT,
+        description="Nuxt 3 with Litestar API backend",
+        vite_plugin=None,
+        dependencies=["nuxt", "vue"],
+        dev_dependencies=["typescript", "vue-tsc", "litestar-vite-plugin"],
+        files=["nuxt.config.ts", "app.vue", "pages/index.vue", "composables/useApi.ts"],
+        uses_typescript=True,
+        has_ssr=True,
+        inertia_compatible=False,
+    ),
+    FrameworkType.ASTRO: FrameworkTemplate(
+        name="Astro",
+        type=FrameworkType.ASTRO,
+        description="Astro with Litestar API backend",
+        vite_plugin="litestar-vite-plugin/astro",
+        dependencies=["astro"],
+        dev_dependencies=["typescript", "litestar-vite-plugin"],
+        files=["astro.config.mjs", "src/pages/index.astro", "src/layouts/Layout.astro", "src/styles/global.css"],
+        uses_typescript=True,
+        has_ssr=True,
+        inertia_compatible=False,
+    ),
+    FrameworkType.HTMX: FrameworkTemplate(
+        name="HTMX",
+        type=FrameworkType.HTMX,
+        description="Server-rendered HTML with HTMX",
+        vite_plugin=None,
+        dependencies=["htmx.org"],
+        dev_dependencies=["typescript"],
+        files=["vite.config.ts", "resources/main.js", "templates/base.html.j2", "templates/index.html.j2"],
+        uses_typescript=False,
+        has_ssr=False,
+        inertia_compatible=False,
+        resource_dir="resources",
+    ),
+    FrameworkType.ANGULAR: FrameworkTemplate(
+        name="Angular (Vite)",
+        type=FrameworkType.ANGULAR,
+        description="Angular 21+ with Vite (zoneless signals)",
+        vite_plugin="@analogjs/vite-plugin-angular",
+        dependencies=[
+            "@angular/animations",
+            "@angular/common",
+            "@angular/compiler",
+            "@angular/core",
+            "@angular/forms",
+            "@angular/platform-browser",
+            "rxjs",
+        ],
+        dev_dependencies=[
+            "@analogjs/vite-plugin-angular",
+            "@angular/build",
+            "@angular/compiler-cli",
+            "@angular/platform-browser-dynamic",
+            "typescript",
+            "@types/node",
+        ],
+        files=[
+            "vite.config.ts",
+            "tsconfig.json",
+            "tsconfig.app.json",
+            "package.json",
+            "index.html",
+            "src/main.ts",
+            "src/styles.css",
+            "src/app/app.component.ts",
+            "src/app/app.component.html",
+            "src/app/app.component.css",
+            "src/app/app.config.ts",
+        ],
+        uses_typescript=True,
+        has_ssr=False,
+        inertia_compatible=False,
+        uses_vite=True,
+        resource_dir="src",
+    ),
+    FrameworkType.ANGULAR_CLI: FrameworkTemplate(
+        name="Angular CLI",
+        type=FrameworkType.ANGULAR_CLI,
+        description="Angular 21+ with zoneless signals and TailwindCSS (Angular CLI)",
+        vite_plugin=None,
+        dependencies=[
+            "@angular/animations",
+            "@angular/common",
+            "@angular/compiler",
+            "@angular/core",
+            "@angular/forms",
+            "@angular/platform-browser",
+            "@angular/platform-browser-dynamic",
+            "rxjs",
+            "@tailwindcss/postcss",
+            "tailwindcss",
+        ],
+        dev_dependencies=[
+            "@angular-devkit/build-angular",
+            "@angular/cli",
+            "@angular/compiler-cli",
+            "@types/node",
+            "typescript",
+            "postcss",
+            "autoprefixer",
+        ],
+        files=[
+            "angular.json",
+            "tsconfig.json",
+            "tsconfig.app.json",
+            "tsconfig.spec.json",
+            "package.json",
+            "proxy.conf.json",
+            ".postcssrc.json",
+            "tailwind.config.js",
+            "src/index.html",
+            "src/main.ts",
+            "src/styles.css",
+            "src/app/app.component.ts",
+            "src/app/app.component.html",
+            "src/app/app.component.css",
+            "src/app/app.config.ts",
+        ],
+        uses_typescript=True,
+        has_ssr=False,
+        inertia_compatible=False,
+        uses_vite=False,
+        resource_dir="src",
+    ),
+}
+
+
+def get_available_templates() -> list[FrameworkTemplate]:
+    """Get all available framework templates.
+
+    Returns:
+        List of available FrameworkTemplate instances.
+    """
+    return list(FRAMEWORK_TEMPLATES.values())
+
+
+def get_template(framework_type: "FrameworkType | str") -> "FrameworkTemplate | None":
+    """Get a specific framework template.
+
+    Args:
+        framework_type: The framework type (enum or string).
+
+    Returns:
+        The FrameworkTemplate if found, None otherwise.
+    """
+    if isinstance(framework_type, FrameworkType):
+        return FRAMEWORK_TEMPLATES.get(framework_type)
+    try:
+        return FRAMEWORK_TEMPLATES.get(FrameworkType(framework_type))
+    except ValueError:
+        return None