{
  "schema_version": 1,
  "skill_name": "vite",
  "evals": [
    {
      "id": "diagnose-build-failure",
      "prompt": "A Vite production build fails with a module not found error after a dependency upgrade. Explain the investigation and safe fix.",
      "expected_output": "An evidence-first diagnosis that identifies the package manager and lockfile, records Node/Vite/plugin versions, checks the import and workspace dependency declaration, and distinguishes config, resolution, plugin, and typecheck failures. It avoids deleting the lockfile or adding broad aliases, makes the smallest approved change, and reruns the declared build with a bounded timeout.",
      "assertions": [
        "The response inspects package manager, lockfile, Node, Vite, and plugin evidence",
        "The response checks the import and workspace dependency before changing aliases",
        "The response forbids deleting the lockfile as a first fix",
        "The response reruns the declared production build and reports the boundary result"
      ],
      "case_set": "regression"
    },
    {
      "id": "env-secret-boundary",
      "prompt": "We need to expose a public API URL in a Vite React app, but the same .env file also contains a private API token. What should change?",
      "expected_output": "The response explains that only intentionally prefixed variables such as VITE_API_URL are exposed to client code, while a private token must remain server-side and must not be placed in VITE_* variables, define, committed files, or logs. It verifies variable presence without printing values and restarts the dev server after env changes.",
      "assertions": [
        "Public VITE-prefixed configuration is distinguished from private secrets",
        "The private token is kept server-side and excluded from define, bundles, commits, and logs",
        "The response validates presence without printing values",
        "The response notes that the dev server must restart after env changes"
      ],
      "case_set": "release"
    },
    {
      "id": "base-path-deployment",
      "prompt": "The Vite build works at localhost root but fails when deployed under /docs/ and client-side deep links return 404. Give a verification and remediation plan.",
      "expected_output": "A plan that checks the configured base against the hosting prefix, inspects generated HTML and dynamic asset URLs, confirms the exact outDir is published, and configures SPA fallback or a host-compatible routing strategy. It verifies the root and a deep route through preview or the deployed boundary, rather than treating build success as sufficient.",
      "assertions": [
        "The response aligns base with the /docs/ hosting prefix",
        "The response checks generated HTML, dynamic imports, and the exact output directory",
        "The response addresses SPA fallback for deep links",
        "The response verifies root and deep routes at the deployed boundary"
      ],
      "case_set": "regression"
    },
    {
      "id": "dev-host-exposure",
      "prompt": "A teammate wants to run vite --host 0.0.0.0 so a phone can access the app. What should we inspect and what risks must be acknowledged?",
      "expected_output": "The response treats binding all interfaces as a scoped exposure change: inspect host, port, strictPort, proxy, firewall/network scope, and whether development endpoints or upstream targets become reachable. It proposes the narrowest approved host and verifies access from the intended device without exposing credentials or assuming preview is production-safe.",
      "assertions": [
        "Binding all interfaces is identified as an exposure and network-scope change",
        "Host, port, proxy, and network controls are inspected before changing them",
        "The response chooses the narrowest approved access and verifies the intended device",
        "The response does not expose credentials or call vite preview a production server"
      ],
      "case_set": "release"
    },
    {
      "id": "browser-and-accessibility-boundary",
      "prompt": "We changed vite.config.ts and want to claim the app still works and remains accessible. Which checks belong in the Vite workflow and which skills should handle the rest?",
      "expected_output": "The response runs config validation and a production build, inspects output paths, and uses Vite preview for production-like serving. It routes browser user-flow assertions to Playwright and WCAG or semantic accessibility review to web-accessibility, while routing UI architecture to frontend-engineering and CI or hosting topology to platform-engineering.",
      "assertions": [
        "The Vite workflow includes config/build and output-path verification",
        "Browser user-flow claims are routed to Playwright",
        "Accessibility claims are routed to web-accessibility",
        "UI architecture and CI/hosting concerns are routed to frontend-engineering and platform-engineering"
      ],
      "case_set": "dev"
    }
  ]
}

# Vite Builds And Deployment

## Build diagnosis

Start with the first actionable error from the project's declared build script. Record Node, package-manager, Vite, framework-plugin, and lockfile evidence before changing dependencies. Typical layers are: config loading, dependency resolution, plugin transform, TypeScript/type checking, asset URL generation, chunking, and output writing.

Do not fix a missing module by adding a broad alias or deleting the lockfile. Check whether the import is misspelled, whether the dependency is declared in the correct workspace, whether an optional peer is missing, and whether the package manager install is reproducible. Only reinstall or clear a cache after confirming the cache is generated and the target is safe to remove.

## Output contract

`build.outDir` is relative to the Vite root unless configured otherwise. Confirm that deployment publishes that exact directory and does not accidentally publish source or a stale prior build. Keep generated output out of source control unless the host explicitly requires it.

`base` rewrites asset URLs. A root-relative build can work locally and fail under `/docs/` or a reverse proxy prefix. Verify HTML references, CSS URLs, dynamic imports, and client-side router fallback under the real prefix. Static hosting needs an SPA fallback for routes that are not physical files; alternatively use a routing strategy compatible with the host.

Treat build warnings as evidence, not noise. Review large chunks, dynamic-import boundaries, circular dependencies, and mixed ESM/CJS warnings. Performance budgets and UI architecture route to [frontend-engineering](../../frontend-engineering/SKILL.md); CI and hosting topology route to [platform-engineering](../../platform-engineering/SKILL.md).

## Safe verification sequence

1. Run typecheck/lint where declared.
2. Run the package manager's build script with a bounded timeout.
3. List output files and inspect generated HTML for expected asset paths.
4. Start preview only on the intended interface and port.
5. Check the deployed or previewed root and representative deep route with [Playwright](../../playwright/SKILL.md).
6. Run accessibility checks through [web-accessibility](../../web-accessibility/SKILL.md) when the task makes accessibility claims.

A successful build proves compilation and output generation, not correct routing, browser behavior, or accessibility.

# Vite Configuration And Environments

## Inspect the loading model

Vite loads `vite.config.js`, `vite.config.ts`, or an equivalent config from the project root unless the command supplies another root/config. Read the package script and config together: a monorepo may set `root`, and a config may be asynchronous or mode-aware.

Common precedence for variables loaded by Vite is mode-specific local, mode-specific, general local, then general env files, with existing process environment taking precedence. Confirm the exact behavior against the installed Vite version before relying on subtle precedence. `.env*` files are loaded at startup, so restart the dev server after edits.

Only variables with the configured public prefix (normally `VITE_`) are exposed to client code through `import.meta.env`. This is an exposure boundary, not a secret store. Keep API keys, passwords, signing material, and internal credentials server-side. Do not print env values in diagnostics or commit `.env.local`.

## Config review checklist

- `base` matches the URL prefix where static files are served; use `/` for domain-root hosting and a repository path only when hosting requires it.
- `root` and `publicDir` point at intended directories; public files are copied as-is and should not contain secrets.
- Aliases resolve consistently in Vite, TypeScript, tests, and the editor; prefer absolute filesystem paths in config.
- Framework plugins match the framework and installed Vite major; inspect plugin peer dependencies before upgrading.
- `define` contains only deliberate compile-time constants. Never interpolate untrusted or secret process values into it.
- `server.proxy` is development-only unless the deployment has an equivalent reverse proxy; document target and path rewriting.
- `resolve.dedupe` and dependency optimization settings are added only for a demonstrated duplicate or prebundle problem.

## Modes and scripts

Keep mode selection explicit (`vite --mode staging`, `vite build --mode production`) and ensure the build script's mode matches the deployment contract. Avoid assuming `NODE_ENV` selects a Vite mode. Test required variables by name and presence, not by logging their values.

For SSR or library mode, use the project's framework and package contract: client-only assumptions about `import.meta.env`, HTML entry files, and `outDir` may not apply. A library build has different externalization and output expectations than an application build.

## Change and verify

Make one config change at a time. Run the project's typecheck/lint if available, then a production build. Inspect the generated HTML and asset references under `outDir`; if `base` is non-root, test a deep link and an asset URL at that prefix. Route browser-level verification to [Playwright](../../playwright/SKILL.md) and accessibility verification to [web-accessibility](../../web-accessibility/SKILL.md).

# Vite Dev Server And Diagnostics

## Dev versus preview

`vite` serves the source graph with hot module replacement and development middleware. `vite preview` serves the already-built output and is useful for checking production-like asset paths; it is not a production server. Read scripts and config before invoking either.

Inspect `server.host`, `server.port`, `server.strictPort`, `server.open`, `server.proxy`, and `preview` settings. Binding to localhost limits access to the local machine. Binding to all interfaces can expose source, proxy targets, or development endpoints to the LAN; do so only with an explicit scope and network review. Never treat `--host 0.0.0.0` as a harmless default.

## Diagnostic order

1. Run `scripts/vite-doctor --project PATH --json` and record tool availability without printing variable values.
2. Read `package.json`, lockfile, config, and workspace boundaries.
3. Reproduce with the smallest declared command and a bounded timeout.
4. Classify the failure as config, dependency, plugin transform, server bind/proxy, browser runtime, or deployment routing.
5. Change one layer, rerun, and preserve the first useful error.

For proxy failures, verify the browser request URL, configured rewrite, target reachability, and CORS/auth expectations separately. A dev proxy can hide a production CORS or reverse-proxy issue. For HMR failures, inspect websocket URL, host/port, proxy upgrades, and browser console; do not immediately disable HMR.

## Script boundary

The bundled doctor is read-only and bounded. It reports Node and package-manager version commands, installed Vite package metadata, config filenames, package-manager lockfiles, and environment variable names (not values). It does not install packages, start servers, read `.env` contents, or modify the project. Use it before any potentially mutating command.

from __future__ import annotations

import json
import subprocess
import tempfile
import unittest
from pathlib import Path

SCRIPT = Path(__file__).with_name("vite-doctor")


class ViteDoctorTest(unittest.TestCase):
    def run_doctor(self, project: Path, *extra: str) -> subprocess.CompletedProcess[str]:
        return subprocess.run(
            [str(SCRIPT), "--project", str(project), "--json", *extra],
            text=True,
            capture_output=True,
            check=False,
        )

    def test_reports_lock_config_and_names_without_env_values(self) -> None:
        with tempfile.TemporaryDirectory() as directory:
            project = Path(directory)
            (project / "package.json").write_text(
                json.dumps({"devDependencies": {"vite": "^6.0.0"}}), encoding="utf-8"
            )
            (project / "pnpm-lock.yaml").write_text("lockfileVersion: 9\n", encoding="utf-8")
            (project / "vite.config.ts").write_text("export default {}\n", encoding="utf-8")
            (project / ".env.local").write_text("VITE_PUBLIC=do-not-print\nSECRET=never-print\n", encoding="utf-8")
            result = self.run_doctor(project)
            self.assertEqual(0, result.returncode)
            payload = json.loads(result.stdout)
            self.assertEqual("pnpm", payload["package_manager"]["name"])
            self.assertEqual(["vite.config.ts"], payload["config_files"])
            self.assertEqual([".env.local"], payload["env_file_names"])
            self.assertIn("^6.0.0", json.dumps(payload))
            self.assertNotIn("do-not-print", result.stdout)
            self.assertNotIn("never-print", result.stdout)

    def test_reports_resolved_package_and_binary_versions(self) -> None:
        with tempfile.TemporaryDirectory() as directory:
            project = Path(directory)
            (project / "package.json").write_text(
                json.dumps({"devDependencies": {"vite": "^6.0.0"}}), encoding="utf-8"
            )
            package_dir = project / "node_modules" / "vite"
            package_dir.mkdir(parents=True)
            (package_dir / "package.json").write_text(
                json.dumps({"name": "vite", "version": "6.1.2"}), encoding="utf-8"
            )
            binary = project / "node_modules" / ".bin" / "vite"
            binary.parent.mkdir(parents=True)
            binary.write_text("#!/bin/sh\nprintf 'vite/6.1.2 node/22.0.0\\n'\n", encoding="utf-8")
            binary.chmod(0o755)
            result = self.run_doctor(project)
            self.assertEqual(0, result.returncode)
            payload = json.loads(result.stdout)
            self.assertEqual("6.1.2", payload["vite_resolved"]["package"]["version"])
            self.assertEqual("vite/6.1.2 node/22.0.0", payload["vite_resolved"]["executable"]["version"])

    def test_reports_resolved_absence_without_installing(self) -> None:
        with tempfile.TemporaryDirectory() as directory:
            project = Path(directory)
            (project / "package.json").write_text(
                json.dumps({"dependencies": {"vite": "~5.4.0"}}), encoding="utf-8"
            )
            result = self.run_doctor(project)
            self.assertEqual(0, result.returncode)
            resolved = json.loads(result.stdout)["vite_resolved"]
            self.assertFalse(resolved["package"]["available"])
            self.assertFalse(resolved["executable"]["available"])

    def test_missing_project_is_bounded_error(self) -> None:
        result = self.run_doctor(Path("/path/that/does/not/exist"))
        self.assertEqual(1, result.returncode)
        self.assertIn("not a directory", result.stderr)

    def test_invalid_timeout_is_usage_error(self) -> None:
        with tempfile.TemporaryDirectory() as directory:
            result = self.run_doctor(Path(directory), "--timeout", "0")
            self.assertEqual(2, result.returncode)
            self.assertIn("positive", result.stderr)


if __name__ == "__main__":
    unittest.main()