Initial Commit

packages/devtools/tooling/test-vite/src/vite-app-config/vite-app-config.md

@@ -0,0 +1,54 @@
+# vite-app-config
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`createViteAppConfig` builds a Vite `UserConfig` tailored for consumer applications rather than library packages. It defaults to hashed asset filenames so long-term caching works out of the box, targets `es2022` to match the project's TypeScript output, and configures `envPrefix` so the standard `VITE_*` (or any caller-supplied prefix) is the only env surface exposed to client bundles.
+
+## Features
+
+- Hashed asset / chunk / entry filenames under `assets/[name]-[hash][extname]`.
+- `target: 'es2022'` default to match the `tsconfig.base.json` setting.
+- `envPrefix` default `['VITE_']` with full opt-in override.
+- Zod-validated option boundary; bad input throws `TestViteError(TEST_VITE.INVALID_OPTIONS)`.
+- OTel counter `test_vite_config_built_total{kind="vite_app"}` incremented per invocation.
+
+## Usage: Basic
+
+```ts
+// vite.config.ts
+import { createViteAppConfig } from "@suaveplan/test-vite/vite-app-config";
+
+export default createViteAppConfig({ root: __dirname });
+```
+
+## Usage: Advanced
+
+Custom env prefix + plugins:
+
+```ts
+import react from "@vitejs/plugin-react";
+import { createViteAppConfig } from "@suaveplan/test-vite/vite-app-config";
+
+export default createViteAppConfig({
+  root: __dirname,
+  outDir: "dist",
+  target: "es2023",
+  envPrefix: ["APP_", "PUBLIC_"],
+  sourcemap: true,
+  plugins: [react()],
+});
+```
+
+## API Reference
+
+- `createViteAppConfig(opts: ViteAppConfigOptions): UserConfig`.
+- `ViteAppConfigOptions` — `{ root, outDir?, target?, envPrefix?, sourcemap?, plugins? }`.
+- Throws `TestViteError` with code `TEST_VITE.INVALID_OPTIONS` on Zod failure.
+
+## Implementation Notes
+
+The factory normalises `envPrefix` to a string array even when only one prefix is supplied so downstream tooling can iterate uniformly. Asset hashing uses the standard Rollup placeholders; consumers that need a different layout can spread the returned config and override `build.rollupOptions.output`. The factory does not register a framework plugin — pass `react()`, `vue()`, or another framework plugin through the `plugins` option so the factory stays framework-agnostic and you keep one source of truth for plugin order. The Zod boundary rejects unknown options strictly so typos surface immediately at build time rather than failing silently inside Vite.