@greendrake/vite-preset 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eugene Greendrake
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# @greendrake/vite-preset
+
+A Vite config factory and build-env helpers for Vue 3 single-page apps. `vueSpa()` owns the conventions an app would otherwise hand-copy: the Vue plugin, the strict `VITE_PORT` pin, the `@` alias, the dedupe list, unhashed font asset names and an HMR guard against circular imports. Apps pass app-specific config through `overrides`, which is deep-merged last.
+
+The package is Node-only, except the `./api-target` entry, which is pure and also runs in the browser bundle. It ships TypeScript, and Node does not type-strip files under `node_modules`, so a `vite.config.ts` importing it runs under bun: `bun --bun vite …`.
+
+## Install
+
+```sh
+bun add -d @greendrake/vite-preset vite
+```
+
+`@vitejs/plugin-vue` comes with the package; `vite` (≥ 8) is a peer dependency.
+
+## `vueSpa(options)`
+
+```ts
+import { defineConfig } from 'vite'
+import { vueSpa } from '@greendrake/vite-preset'
+
+export default defineConfig(
+    vueSpa({
+        dirname: import.meta.dirname,
+        define: { __API_URL__: process.env.API_URL },
+        overrides: { plugins: [myPlugin()] }
+    })
+)
+```
+
+| Option | Effect |
+| --- | --- |
+| `dirname` | The app root (`import.meta.dirname` of the vite config); anchors the `@` alias at `<dirname>/src`. |
+| `define` | Compile-time globals. Values are serialised for you: a string becomes a string literal, a boolean `true`/`false`, an object an object literal. |
+| `scssLoadPaths` | Extra `@use` resolution roots for Sass (e.g. the app's `src/scss`). |
+| `port` | `'env'` (default): `VITE_PORT` is required whenever a server starts. A number pins that port. `false` disables pinning, for an app served on any free port. |
+| `htmlPlaceholders` | Literal substitutions applied to `index.html` before Vite processes it (see `htmlPlaceholders` below). |
+| `htmlMinify` | Minify `index.html`, inline scripts and styles included, in production builds. |
+| `staticRoots` | Directories outside the app served at public URL prefixes (see `staticRoots` below). |
+| `overrides` | A `UserConfig` deep-merged last — the escape hatch for `server.proxy`, extra plugins, build tweaks. |
+
+What the preset sets:
+
+- plugins: `@vitejs/plugin-vue` and the HMR circular-import guard, plus the `staticRoots`, `htmlPlaceholders` and `htmlMinify` plugins when their options are given;
+- `server.port`/`preview.port` from `VITE_PORT` with `strictPort`, for `vite dev` and `vite preview` only — builds run in deploy contexts that never define a dev port;
+- `server.fs.allow`: the parent of the app root (a workspace), and every static root's directory;
+- `resolve.alias`: `@` → `<dirname>/src`; `resolve.dedupe`: `vue`, `pinia`, `vue-router` — each must also be a direct dependency of the app, or Vite fails to resolve it;
+- `optimizeDeps`: every source-shipped dependency of the app is excluded from pre-bundling, and `vue`, `pinia` and `vue-router` (those the app declares) are pinned into it. A source-shipped package is TypeScript and SFC rather than a build; pre-bundling one from `node_modules` would inline its TypeScript modules and their imports while externalising its `.vue` files, leaving the app with two copies of Pinia and everything else. Served raw, a package resolves to one copy of itself and meets the app on the pre-bundled framework modules. Workspace-linked packages are never pre-bundled, so in a monorepo the exclusion decides no pre-bundling either way — it still matters for what the scanner sees, below. Which dependencies those are is the `sourcePackages` option — an entry ending in `/` matches a whole scope, anything else an exact package name. It defaults to `['@greendrake/']`; an app with source packages of its own lists them, and lists that scope again if it uses any:
+
+  ```ts
+  vueSpa({ dirname: import.meta.dirname, sourcePackages: ['@greendrake/', '@acme/ui', 'my-design-system'] })
+  ```
+
+  Excluding a package also hides it from Vite's dependency scanner, which externalises every excluded id and so never reads what that package imports. The third-party packages behind a source package are therefore pinned into the pre-bundle too, or the first browser request for one is a discovery: Vite re-runs the optimiser mid-session and full-reloads every open page — which under a parallel E2E run lands in the middle of tests in flight. The preset walks the app's runtime dependencies, follows the source packages among them, and pins each package they depend on, plus each peer they declare that the app itself supplies at runtime. Each is named in Vite's `parent > child` form unless the app declares it too, in which case its plain name — the id the scanner itself would produce — is used instead. Two things are left out: a package published only under subpaths, which no `optimizeDeps` entry can name and which Vite reaches through the subpath ids that import it anyway; and anything behind a source package the app keeps among its dev dependencies, which by the app's own reckoning is tooling (a build-tool integration shipped beside a package's components, a native-build helper) that browser code never reaches. That split is what an app is asserting when it puts a package in one list rather than the other, so put build-time source packages in `devDependencies`.
+
+- `build`: font files (`woff2`, `woff`, `eot`, `ttf`, `otf`) are emitted unhashed under `assets/fonts/`, so `index.html` can prefetch them by a stable name; everything else is hashed.
+
+`vueSpa` returns the *function* form of a Vite config (`ConfigEnv → UserConfig`). An app that needs the `ConfigEnv` before building its options wraps the call itself:
+
+```ts
+export default defineConfig(configEnv =>
+    vueSpa({
+        dirname: import.meta.dirname,
+        define: { __API_TARGET_ENV__: apiTargetEnv(configEnv.command === 'serve') }
+    })(configEnv)
+)
+```
+
+### HMR circular-import guard
+
+An HMR update whose accepted module sits inside an import cycle cannot be re-executed reliably; Vite's client masks that with a silent full-page reload. The preset intercepts such updates on the dev server and replaces them with an error overlay naming the offending modules, so the cycle gets broken rather than papered over. `vite --debug hmr` logs its path.
+
+## Env helpers
+
+```ts
+import { loadAppEnv, requirePort, envBool, deriveImageBaseUrl, apiTargetEnv, buildHash } from '@greendrake/vite-preset'
+```
+
+- `loadAppEnv(mode, dirname)` — the app's `.env` / `.env.<mode>` files, every key (not only `VITE_`-prefixed ones): they carry plain build inputs, and the `export` prefix they may be written with is stripped so the same file can be shell-sourced. `process.env` outranks the file. Do not name the files `.env.development` / `.env.production`: bun auto-loads those into `process.env` at startup, and whichever one it picked would then outrank the mode's file. `@greendrake/dash/vite` builds its dashboard convention on this.
+- `requirePort()` — `VITE_PORT`, required; the single port convention.
+- `envBool(value)` — `"1"`, `"t"`, `"true"` (any case) are true; `"0"`, `"false"`, unset and everything else are false. `Boolean(process.env.X)` would take the literal string `"0"` as true.
+- `deriveImageBaseUrl(env = process.env)` — the prefix for object-storage image URLs. A defined `S3_PREFIX` wins outright, even when empty; otherwise `AWS_S3_ENDPOINT/AWS_S3_BUCKET`; otherwise `''`.
+- `apiTargetEnv(dev, paths?)` — the `ApiTargetEnv` of `resolveApiTarget`, read from `API_PORT`, `PUBLIC_FE_HOST`, `PUBLIC_API_HOST`, with optional `apiPath`/`wsPath`. Bake it into one define and feed the same object to anything else that resolves the host.
+- `buildHash()` — `git rev-parse --short HEAD`, for a `__BUILD_HASH__` define. If git fails the build fails.
+
+## Plugins
+
+### `htmlPlaceholders(map)`
+
+Substitutes build-time values into `index.html` before Vite processes it — a generated inline script, a build hash, PWA metadata. Keys are matched literally (convention: `__NAME__`); an empty map is an error. `vueSpa`'s `htmlPlaceholders` option installs it.
+
+### `htmlMinify()`
+
+Production-only: collapses whitespace, strips comments, minifies inline JS and CSS in `index.html`. Dev keeps the source readable. Installed by the `htmlMinify` option.
+
+### `staticRoots(roots)` and `staticRootFiles(root)`
+
+Some assets belong to the product rather than to the frontend — a locale catalogue a backend renders from too, prose a content page shows. A `StaticRoot` is `{ dir, urlPath, transform? }`: an absolute directory, the URL prefix it appears under (e.g. `/i18n`), and an optional per-file rewrite applied on the way out. The plugin serves the root by middleware in dev and copies it into `dist/` at build, so the two modes publish the same bytes; `.yaml`/`.yml` and `.json` get their content types, anything else is `text/plain`. Requests cannot climb out of the root. `staticRootFiles(root)` lists what a root publishes as URL paths, for a service worker's precache list. Installed by the `staticRoots` option.
+
+## `./api-target`
+
+```ts
+import { resolveApiTarget, browserRuntime } from '@greendrake/vite-preset/api-target'
+```
+
+The single source of truth for where the API lives, pure and environment-free, so the same rules serve a vite config and the browser bundle. `resolveApiTarget(env, runtime?)` returns `{ apiUrl, wsUrl }`:
+
+- dev (`env.dev`): `http`/`ws` against `localhost:<env.apiPort>`; with `env.publicApiHost` set instead, `https`/`wss` against that host (a dev server pointed at a remote API). Neither set is an error.
+- prod: the same bundle can be served on two hosts. On `env.publicFeHost` — where a CDN may not proxy WebSockets — the API is `env.publicApiHost`; on any other host it is same-origin, i.e. `runtime.host`. The scheme follows `runtime.https`. `runtime` is required, and `publicApiHost` is required when serving on `publicFeHost`.
+- `env.apiPath` and `env.wsPath` replace the default `/v1/api` and `/v1/ws`; a backend that routes at the host root sets `apiPath: ''`.
+
+`browserRuntime()` is the `runtime` argument as a browser bundle supplies it: `{ host: location.host, https: location.protocol === 'https:' }`.
+
+## Sass: import shared style packages by bare specifier
+
+`@use '@greendrake/font-inter'` — never `@use 'pkg:@greendrake/font-inter'`, and do not register Sass's `NodePackageImporter`.
+
+Vite resolves bare specifiers with its own Sass importer and rebases relative `url()` references inside the imported package against that package's own source location, so `@font-face { src: url('./fonts/X.woff2') }` in a font package resolves, gets emitted into `dist/assets/`, and the emitted CSS points at the built asset.
+
+`NodePackageImporter` resolves the same `@use` to a path Vite's CSS pipeline does not rebase against. The `url()` then survives verbatim into the output, no font asset is emitted, and the build warns `didn't resolve at build time, it will remain unchanged to be resolved at runtime` — every font 404s at runtime. This is a property of the importer, not of any Vite version.
+
+The corollary, enforced by `@greendrake/scss-kit`'s `_font-face.scss`: the `url()` literal must be written in the owning package's own `.scss`, because that is the file the rebasing is relative to.
+
+If a future Vite drops bare-specifier support, migrate to `loadPaths` or move the `@font-face` blocks into the consuming apps — not to `pkg:`.

package/package.json

@@ -0,0 +1,56 @@
+{
+    "name": "@greendrake/vite-preset",
+    "version": "0.1.0",
+    "description": "Vite config factory and build-env helpers for Vue 3 single-page apps: plugin set, strict dev port, alias, dedupe and source-package pre-bundling rules",
+    "license": "MIT",
+    "author": "Eugene Greendrake <eugene@greendrake.nz>",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/greendrake/lib.git",
+        "directory": "vite-preset"
+    },
+    "homepage": "https://github.com/greendrake/lib/tree/main/vite-preset#readme",
+    "bugs": {
+        "url": "https://github.com/greendrake/lib/issues"
+    },
+    "type": "module",
+    "main": "src/main.ts",
+    "types": "src/main.ts",
+    "exports": {
+        ".": {
+            "types": "./src/main.ts",
+            "default": "./src/main.ts"
+        },
+        "./api-target": {
+            "types": "./src/apiTarget.ts",
+            "default": "./src/apiTarget.ts"
+        }
+    },
+    "files": [
+        "src"
+    ],
+    "sideEffects": false,
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "check": "tsc --noEmit"
+    },
+    "prettier": "@greendrake/dev-config/prettier",
+    "dependencies": {
+        "@greendrake/util": "0.1.0",
+        "@vitejs/plugin-vue": "^6.0.7",
+        "html-minifier-terser": "^7.2.0"
+    },
+    "peerDependencies": {
+        "vite": ">=8"
+    },
+    "devDependencies": {
+        "@greendrake/dev-config": "0.1.0",
+        "@types/bun": "^1.3.5",
+        "@types/html-minifier-terser": "^7.0.2",
+        "@types/node": "^24.0.0",
+        "typescript": "6.0.3",
+        "vite": "^8.2.1"
+    }
+}

package/src/apiTarget.ts

@@ -0,0 +1,84 @@
+// Single source of truth for where the API lives. Pure and environment-free:
+// build-time inputs (env) and runtime inputs (the page's location) are
+// explicit arguments, so the same rules serve the Node side (vite configs,
+// inline bootstrap generation) and the browser bundle — import via the
+// ./api-target subpath there; the package's main entry is Node-only.
+//
+// Host resolution:
+//   Prod — the same bundle is deployed to two hosts. On the public FE host
+//   (e.g. example.com) a CDN may not proxy WS, so the API is on its own host
+//   (e.g. api.example.com). On any other host (e.g. an internal staging host) the API is
+//   proxied same-origin, so use the page's host. Proto follows the page's
+//   (http→ws, https→wss).
+//   Dev — the local backend on apiPort over http/ws; unless publicApiHost is
+//   set (point the dev server at a remote API, e.g. prod), in which case that
+//   host over https/wss.
+
+export interface ApiTargetEnv {
+    // True under `vite dev` (command === 'serve'); false in production builds.
+    dev: boolean
+    apiPort?: string
+    publicFeHost?: string
+    publicApiHost?: string
+    // Endpoint paths appended to the resolved origin (defaults /v1/api and
+    // /v1/ws). A backend that routes POST at the host root sets apiPath: ''.
+    apiPath?: string
+    wsPath?: string
+}
+
+export interface ApiTargetRuntime {
+    // The page's location.host / location.protocol === 'https:'. Only
+    // consulted in prod — dev targets are fully determined by env.
+    host: string
+    https: boolean
+}
+
+export interface ApiTarget {
+    apiUrl: string
+    wsUrl: string
+}
+
+export const resolveApiTarget = (env: ApiTargetEnv, runtime?: ApiTargetRuntime): ApiTarget => {
+    let host: string
+    let secure: boolean
+    if (env.dev) {
+        if (env.publicApiHost) {
+            host = env.publicApiHost
+            secure = true
+        } else {
+            if (!env.apiPort) {
+                throw new Error('resolveApiTarget: apiPort is required in local dev (no publicApiHost)')
+            }
+            host = `localhost:${env.apiPort}`
+            secure = false
+        }
+    } else {
+        if (!runtime) {
+            throw new Error('resolveApiTarget: runtime location is required in prod (the dual-host rule resolves against it)')
+        }
+        if (env.publicFeHost && runtime.host === env.publicFeHost) {
+            if (!env.publicApiHost) {
+                throw new Error('resolveApiTarget: publicApiHost is required when serving on publicFeHost')
+            }
+            host = env.publicApiHost
+        } else {
+            host = runtime.host
+        }
+        secure = runtime.https
+    }
+    return {
+        apiUrl: `${secure ? 'https' : 'http'}://${host}${env.apiPath ?? '/v1/api'}`,
+        wsUrl: `${secure ? 'wss' : 'ws'}://${host}${env.wsPath ?? '/v1/ws'}`
+    }
+}
+
+// browserRuntime executes only in browser bundles, but this package's
+// tsconfig is Node-typed (no DOM lib) — declare the two location fields read.
+declare const location: { host: string; protocol: string }
+
+// The runtime argument as a browser bundle supplies it. Apps with no special
+// runtime (native shells etc.) pass this directly.
+export const browserRuntime = (): ApiTargetRuntime => ({
+    host: location.host,
+    https: location.protocol === 'https:'
+})

package/src/env.ts

@@ -0,0 +1,54 @@
+// Build-time (Node) environment helpers shared by app vite configs.
+
+import { execSync } from 'node:child_process'
+import { loadEnv } from 'vite'
+import type { ApiTargetEnv } from './apiTarget'
+
+// The app's own .env / .env.<mode> files, every key (not just VITE_-prefixed
+// ones) — these files carry plain build inputs, and dotenv strips the `export`
+// prefix they are written with so the same file can also be shell-sourced.
+// process.env outranks the file, which makes a deliberate shell export an
+// override but also means an app must not name files `.env.development` /
+// `.env.production`: bun auto-loads those at startup, and whichever one it
+// picked would then outrank the mode's file.
+// Config factories take vite's whole build-env surface through this package so
+// that a downstream factory never resolves its own vite copy.
+export const loadAppEnv = (mode: string, dirname: string): Record<string, string> => loadEnv(mode, dirname, '')
+
+// The build-time inputs of resolveApiTarget, read from the conventional env
+// vars (API_PORT, PUBLIC_FE_HOST, PUBLIC_API_HOST). Apps bake the result into
+// a single define (`__API_TARGET_ENV__`) and feed the same object to anything
+// else that resolves the host, so all of it resolves from one source.
+export const apiTargetEnv = (dev: boolean, paths?: Pick<ApiTargetEnv, 'apiPath' | 'wsPath'>): ApiTargetEnv => ({
+    dev,
+    apiPort: process.env.API_PORT,
+    publicFeHost: process.env.PUBLIC_FE_HOST,
+    publicApiHost: process.env.PUBLIC_API_HOST,
+    ...paths
+})
+
+// `Boolean(process.env.X)` would treat the literal string "0" as true (it's a
+// non-empty string). Parse as a Go-flavoured boolean instead so "0" / "false"
+// / unset all register as off (Go strconv.ParseBool semantics).
+export const envBool = (v: string | undefined): boolean => /^(1|t|true)$/i.test(v ?? '')
+
+// imageBaseUrl is prepended to S3 object keys to form absolute image URLs. An
+// explicitly defined S3_PREFIX wins outright — including when set to empty,
+// which forces the base empty regardless of the AWS_S3_* vars. The check is
+// for definedness (not truthiness) precisely so an empty S3_PREFIX overrides.
+// When S3_PREFIX is unset, derive the base from the S3 endpoint + bucket.
+export const deriveImageBaseUrl = (env: NodeJS.ProcessEnv = process.env): string =>
+    env.S3_PREFIX !== undefined ? env.S3_PREFIX : env.AWS_S3_ENDPOINT && env.AWS_S3_BUCKET ? `${env.AWS_S3_ENDPOINT}/${env.AWS_S3_BUCKET}` : ''
+
+// FE build identifier for a `__BUILD_HASH__` define. If git fails, the
+// build fails (no defensive fallbacks for environmental issues — fix the
+// build environment).
+export const buildHash = (): string => execSync('git rev-parse --short HEAD', { encoding: 'utf-8' }).trim()
+
+// The single port convention: VITE_PORT, required, strict.
+export const requirePort = (): number => {
+    if (!process.env.VITE_PORT) {
+        throw new Error('VITE_PORT environment variable must be set')
+    }
+    return parseInt(process.env.VITE_PORT, 10)
+}

package/src/hmr.ts

@@ -0,0 +1,41 @@
+import type { HotPayload, Plugin } from 'vite'
+
+// An HMR update whose accepted module sits inside an import cycle cannot be
+// re-executed reliably; Vite's client masks that by silently reloading the
+// whole page ("failed to apply HMR as it's within a circular import"), which
+// hides the cycle until it bites in subtler ways. This guard intercepts such
+// updates server-side and replaces them with an error overlay naming the
+// offending modules — the cycle must be broken, not papered over. The client's
+// reload lives outside any public hook (it never emits vite:beforeFullReload),
+// so the payload send is the one interception point.
+export const hmrCircularImportGuard = (): Plugin => ({
+    name: 'greendrake:hmr-circular-import-guard',
+    apply: 'serve',
+    configureServer(server) {
+        const hot = server.environments.client.hot
+        const send = hot.send.bind(hot)
+        hot.send = (payloadOrEvent: HotPayload | string, data?: unknown): void => {
+            if (typeof payloadOrEvent === 'string') {
+                send(payloadOrEvent, data)
+                return
+            }
+            if (payloadOrEvent.type === 'update') {
+                const circular = payloadOrEvent.updates.filter(u => u.isWithinCircularImport)
+                if (circular.length) {
+                    send({
+                        type: 'error',
+                        err: {
+                            message:
+                                `HMR blocked: the update to ${circular.map(u => u.acceptedPath).join(', ')} is within a circular import, ` +
+                                `which cannot hot-apply (Vite would mask this with a full page reload). ` +
+                                `Break the cycle — run \`vite --debug hmr\` to log its path.`,
+                            stack: ''
+                        }
+                    })
+                    return
+                }
+            }
+            send(payloadOrEvent)
+        }
+    }
+})

package/src/html.ts

@@ -0,0 +1,40 @@
+import { minify } from 'html-minifier-terser'
+import type { Plugin } from 'vite'
+
+// Substitutes build-time values into index.html before Vite processes it —
+// e.g. a generated bootstrap snippet, a build hash, PWA metadata. Keys are
+// matched literally (convention: __NAME__).
+export const htmlPlaceholders = (map: Record<string, string>): Plugin => {
+    const keys = Object.keys(map)
+    if (!keys.length) {
+        throw new Error('htmlPlaceholders: empty placeholder map')
+    }
+    const pattern = new RegExp(keys.map(key => key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|'), 'g')
+    return {
+        name: 'greendrake-html-placeholders',
+        transformIndexHtml: {
+            order: 'pre',
+            handler: html => html.replace(pattern, match => map[match])
+        }
+    }
+}
+
+// Production-only HTML minification — strips comments and collapses
+// whitespace in index.html, and runs inline scripts/styles through
+// terser/CSS minification. Dev keeps the source readable.
+export const htmlMinify = (): Plugin => ({
+    name: 'greendrake-html-minify',
+    apply: 'build',
+    transformIndexHtml: {
+        order: 'post',
+        handler: html =>
+            minify(html, {
+                collapseWhitespace: true,
+                removeComments: true,
+                minifyJS: true,
+                minifyCSS: true,
+                useShortDoctype: true,
+                removeRedundantAttributes: true
+            })
+    }
+})

package/src/main.ts

@@ -0,0 +1,155 @@
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import vue from '@vitejs/plugin-vue'
+import { mergeConfig, type ConfigEnv, type UserConfig, type UserConfigFnObject } from 'vite'
+
+export { envBool, deriveImageBaseUrl, loadAppEnv, requirePort, apiTargetEnv, buildHash } from './env'
+// Re-exported so config factories building on vueSpa (e.g.
+// @greendrake/dash/vite) speak this package's vite types: a second vite
+// copy resolved downstream is a structurally unrelated set of the same names.
+export type { ConfigEnv, UserConfig, UserConfigFnObject } from 'vite'
+export { htmlPlaceholders, htmlMinify } from './html'
+export { resolveApiTarget, browserRuntime, type ApiTarget, type ApiTargetEnv, type ApiTargetRuntime } from './apiTarget'
+export { staticRoots, staticRootFiles, type StaticRoot } from './staticRoots'
+import { requirePort } from './env'
+import { htmlPlaceholders, htmlMinify } from './html'
+import { hmrCircularImportGuard } from './hmr'
+import { nestedDependencies, type DeclaredDependencies } from './sourceDeps'
+import { staticRoots as staticRootsPlugin, type StaticRoot } from './staticRoots'
+
+export interface VueSpaOptions {
+    // The app root (import.meta.dirname of the vite config) — anchors the @ alias.
+    dirname: string
+    // Compile-time globals; values are serialized automatically (strings become
+    // string literals, booleans become true/false, objects become object
+    // literals — e.g. the ApiTargetEnv carried by __API_TARGET_ENV__).
+    define?: Record<string, string | number | boolean | object | null | undefined>
+    // Extra scss @use resolution roots (e.g. the app's src/scss).
+    scssLoadPaths?: string[]
+    // 'env' (default): the strict VITE_PORT convention, required when the dev
+    // server starts. A number: that port verbatim, for callers that resolved
+    // the app's env themselves (see @greendrake/dash/vite). false: no
+    // port pinning — for simple apps served on any free port.
+    port?: 'env' | number | false
+    // Build-time placeholder substitution in index.html (see the
+    // htmlPlaceholders plugin) — e.g. injecting an inline bootstrap script.
+    htmlPlaceholders?: Record<string, string>
+    // Minify index.html (incl. inline JS/CSS) in production builds.
+    htmlMinify?: boolean
+    // Directories outside the app served at a public URL prefix — product
+    // assets both stacks own (locale catalogues, content prose). Served by
+    // middleware in dev and copied into dist/ at build, so the two modes
+    // publish the same bytes.
+    staticRoots?: StaticRoot[]
+    // Dependencies that ship TypeScript and SFC source rather than a build, and
+    // so must not be pre-bundled (see optimizeDeps below). An entry ending in
+    // `/` matches every package under that scope; anything else matches a
+    // package by exact name. Defaults to the @greendrake scope, which is
+    // source-shipped by construction — an app with source packages of its own
+    // names them here, and must name the @greendrake scope again if it uses
+    // any.
+    sourcePackages?: string[]
+    // Deep-merged last over the preset — the escape hatch for anything
+    // app-specific (server.proxy, extra plugins, build tweaks).
+    overrides?: UserConfig
+}
+
+// The libraries the app and every component package it renders must share one
+// instance of.
+const FRAMEWORK = ['vue', 'pinia', 'vue-router']
+
+// Source-shipped by construction, so an app that names none of its own still
+// gets the rule that matters for the packages this preset ships beside.
+const SOURCE_PACKAGES = ['@greendrake/']
+
+// The app's own package.json dependencies, split the way it splits them.
+const declaredDependencies = (dirname: string): DeclaredDependencies => {
+    const pkg = JSON.parse(readFileSync(path.join(dirname, 'package.json'), 'utf-8')) as { dependencies?: Record<string, string>; devDependencies?: Record<string, string> }
+    return { runtime: Object.keys(pkg.dependencies ?? {}), dev: Object.keys(pkg.devDependencies ?? {}) }
+}
+
+// The Vite config a Vue 3 single-page app would otherwise assemble for itself:
+// the vue plugin, the strict VITE_PORT pin, workspace fs.allow, the @ alias,
+// the dedupe list (each entry must also be a direct dependency of the app, or
+// Vite fails to resolve it), the pre-bundling rules a source-shipped package
+// needs, and unhashed font asset names so index.html can prefetch them by a
+// stable name.
+//
+// Returns the function form of a Vite config so the VITE_PORT requirement
+// applies only to `vite dev`: a production build runs in deploy contexts that
+// define no dev port.
+export const vueSpa =
+    (options: VueSpaOptions): UserConfigFnObject =>
+    ({ command }: ConfigEnv): UserConfig => {
+        const deps = declaredDependencies(options.dirname)
+        const allDeps = [...deps.runtime, ...deps.dev]
+        const sourcePackages = options.sourcePackages ?? SOURCE_PACKAGES
+        const isSourcePackage = (name: string): boolean => sourcePackages.some(pattern => (pattern.endsWith('/') ? name.startsWith(pattern) : name === pattern))
+        // Only the dev server and preview pin a port, so an app that supplies
+        // none (and never serves) must not be made to produce one.
+        const portPin = command === 'serve' && options.port !== false ? { port: typeof options.port === 'number' ? options.port : requirePort(), strictPort: true } : undefined
+        const base: UserConfig = {
+            define: options.define && Object.fromEntries(Object.entries(options.define).map(([key, value]) => [key, JSON.stringify(value)])),
+            plugins: [vue(), hmrCircularImportGuard(), ...(options.staticRoots?.length ? [staticRootsPlugin(options.staticRoots)] : []), ...(options.htmlPlaceholders ? [htmlPlaceholders(options.htmlPlaceholders)] : []), ...(options.htmlMinify ? [htmlMinify()] : [])],
+            server:
+                command === 'serve'
+                    ? {
+                          ...portPin,
+                          // '..' reaches the workspace an app sits directly
+                          // inside. Anything the dev server must read from
+                          // further afield — a static root beside the backend,
+                          // package source a level or two above an app nested
+                          // deeper — needs its own entry (server.fs.allow in
+                          // the app's overrides), or dev requests for it are
+                          // refused.
+                          fs: { allow: ['..', ...(options.staticRoots ?? []).map(root => root.dir)] }
+                      }
+                    : undefined,
+            // vite preview also loads with command 'serve'; pin it to the same
+            // port convention so E2E runs are deterministic.
+            preview: portPin,
+            resolve: {
+                alias: { '@': path.resolve(options.dirname, './src') },
+                dedupe: FRAMEWORK
+            },
+            // A source-shipped package (see sourcePackages) is TypeScript
+            // and SFC rather than a build. Pre-bundling one from node_modules
+            // splits it in two: esbuild inlines the
+            // TypeScript modules — and whatever they import — into the
+            // pre-bundle, but externalises the .vue files, which then load the
+            // originals and import their own copies of everything (two Pinia
+            // instances, one of which createPinia never registered). Served raw
+            // instead, a source package resolves to one copy of itself, and the
+            // framework libraries it shares with the app are pinned into the
+            // pre-bundle so raw and app-side imports meet on the same optimised
+            // module. Workspace-linked packages are never pre-bundled, so inside
+            // a monorepo the exclusion decides no pre-bundling either way — but
+            // it does hide the package from the dependency scanner, which is why
+            // the third-party packages it imports are named too (see
+            // nestedDependencies).
+            optimizeDeps: {
+                exclude: allDeps.filter(isSourcePackage),
+                include: [...new Set([...FRAMEWORK.filter(name => allDeps.includes(name)), ...nestedDependencies(options.dirname, deps, isSourcePackage)])]
+            },
+            css: options.scssLoadPaths
+                ? {
+                      preprocessorOptions: {
+                          scss: { loadPaths: options.scssLoadPaths }
+                      }
+                  }
+                : undefined,
+            build: {
+                rolldownOptions: {
+                    output: {
+                        assetFileNames: assetInfo => {
+                            if (assetInfo.names?.[0]?.match(/\.(woff2?|eot|ttf|otf)$/)) {
+                                return 'assets/fonts/[name][extname]'
+                            }
+                            return 'assets/[name]-[hash][extname]'
+                        }
+                    }
+                }
+            }
+        }
+        return options.overrides ? mergeConfig(base, options.overrides) : base
+    }

package/src/sourceDeps.ts

@@ -0,0 +1,95 @@
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+
+// The parts of a package.json this walk reads.
+export interface Manifest {
+    dependencies?: Record<string, string>
+    peerDependencies?: Record<string, string>
+    exports?: string | Record<string, unknown>
+}
+
+// What an app declares, split the way the app itself splits it: what it ships
+// to the browser, and what only its tooling reaches.
+export interface DeclaredDependencies {
+    runtime: string[]
+    dev: string[]
+}
+
+// Where the installer put a package: the nearest node_modules at or above
+// `from` holding it.
+const packageDir = (from: string, name: string): string => {
+    for (let dir = from; ; dir = path.dirname(dir)) {
+        const candidate = path.join(dir, 'node_modules', name)
+        if (existsSync(path.join(candidate, 'package.json'))) return candidate
+        if (path.dirname(dir) === dir) throw new Error(`${name} is declared but not installed anywhere above ${from}`)
+    }
+}
+
+const manifest = (dir: string): Manifest => JSON.parse(readFileSync(path.join(dir, 'package.json'), 'utf-8')) as Manifest
+
+// An `optimizeDeps` entry names a package, so a package published only under
+// subpaths (it maps every entry it has, and none of them is `.`) cannot be one.
+// Nor does it need to be: Vite meets such a package through the subpath ids that
+// import it, and whatever pre-bundles those carries it along.
+const hasRootExport = (pkg: Manifest): boolean => {
+    if (pkg.exports === undefined || typeof pkg.exports === 'string') return true
+    const keys = Object.keys(pkg.exports)
+    return keys.includes('.') || !keys.some(key => key.startsWith('.'))
+}
+
+// The third-party packages a source package imports, as `optimizeDeps.include`
+// entries.
+//
+// Vite's dependency scanner externalises every id in `optimizeDeps.exclude`, so
+// it never reads a source package and never sees what that package imports. The
+// first browser request for one of those imports is then a discovery: Vite
+// re-runs the optimiser mid-session and full-reloads every open page. Under a
+// parallel E2E run that reload lands in the middle of whatever tests are in
+// flight, and they fail on a page that vanished under them. Naming the imports
+// up front makes the first optimisation complete instead.
+//
+// The walk starts at the app's runtime dependencies and follows source packages
+// only, since the scanner reads everything else itself.
+export const nestedDependencies = (dirname: string, declared: DeclaredDependencies, isSourcePackage: (name: string) => boolean): string[] => {
+    const entries = new Set<string>()
+    const visited = new Set<string>()
+    const pin = (chain: string[], from: string, name: string): void => {
+        if (!hasRootExport(manifest(packageDir(from, name)))) return
+        // A package the app declares itself resolves from the app root, and its
+        // plain name is the id the scanner would produce for it; naming it
+        // nested as well would pre-bundle the same module twice, once per id.
+        // Anything else is named in Vite's `a > b > c` form, and names the whole
+        // chain from the dependency the app declares: Vite resolves each segment
+        // from the one before it, starting at the app root, and an intermediate
+        // package the app never declares need not be reachable from there.
+        entries.add(declared.runtime.includes(name) ? name : [...chain, name].join(' > '))
+    }
+    const walk = (name: string, chain: string[], from: string): void => {
+        // A source package the app keeps among its dev dependencies is tooling
+        // by the app's own reckoning — a vite integration a package re-exports
+        // beside its components, a native-build helper — and what such a package
+        // carries is unbundleable for a browser that never reaches it anyway.
+        if (visited.has(name) || declared.dev.includes(name)) return
+        visited.add(name)
+        const dir = packageDir(from, name)
+        const pkg = manifest(dir)
+        // A package the app declares resolves from the app root, so it anchors
+        // its own chain however it was reached. Without that, the chain a
+        // package gets would depend on which branch of the walk arrived first.
+        const here = declared.runtime.includes(name) ? [name] : [...chain, name]
+        for (const dep of Object.keys(pkg.dependencies ?? {})) {
+            if (isSourcePackage(dep)) walk(dep, here, dir)
+            else pin(here, dir, dep)
+        }
+        // A peer is the app's to supply, so it counts only where the app does,
+        // at runtime — the same reckoning, applied to what a package leaves to
+        // its consumer.
+        for (const peer of Object.keys(pkg.peerDependencies ?? {})) {
+            if (declared.runtime.includes(peer)) pin(here, dirname, peer)
+        }
+    }
+    for (const name of declared.runtime) {
+        if (isSourcePackage(name)) walk(name, [], dirname)
+    }
+    return [...entries]
+}

package/src/staticRoots.ts

@@ -0,0 +1,84 @@
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import type { Plugin } from 'vite'
+
+// Serving files that live outside the app: an app's `public/` is its own, but
+// some assets belong to the product rather than to the frontend — a locale
+// catalogue the backend renders from too, the prose a content page shows. Those
+// live in shared config, and this plugin puts them at their public URLs in both
+// modes: middleware in dev, a copy into `dist/` at build. One declaration, so
+// the two cannot drift into serving different bytes.
+
+export interface StaticRoot {
+    // Absolute directory to serve.
+    dir: string
+    // URL prefix it appears under, e.g. '/catalogue'.
+    urlPath: string
+    // Rewrites a file's contents on the way out, in both modes. Used for the
+    // locale catalogues, which are served merged over the default locale.
+    transform?: (relativePath: string, contents: string) => string
+}
+
+const contentTypeFor = (file: string): string => {
+    if (file.endsWith('.yaml') || file.endsWith('.yml')) return 'text/yaml; charset=utf-8'
+    if (file.endsWith('.json')) return 'application/json; charset=utf-8'
+    return 'text/plain; charset=utf-8'
+}
+
+// Every file under dir, as paths relative to it.
+const walk = (dir: string): string[] =>
+    readdirSync(dir, { recursive: true, withFileTypes: true })
+        .filter(entry => entry.isFile())
+        .map(entry => path.relative(dir, path.join(entry.parentPath, entry.name)))
+
+// staticRootFiles lists what a root publishes, as scope-relative URL paths —
+// the service worker's precache list needs to name these without duplicating
+// the walk.
+export const staticRootFiles = (root: StaticRoot): string[] =>
+    walk(root.dir).map(rel => `${root.urlPath}/${rel.split(path.sep).join('/')}`)
+
+export const staticRoots = (roots: StaticRoot[]): Plugin => ({
+    name: 'greendrake-static-roots',
+
+    configureServer(server) {
+        server.middlewares.use((req, res, next) => {
+            const url = (req.url ?? '').split('?')[0]
+            const root = roots.find(r => url.startsWith(`${r.urlPath}/`))
+            if (!root) {
+                next()
+                return
+            }
+            const rel = url.slice(root.urlPath.length + 1)
+            // Nothing climbs out of the root: the URL is attacker-controlled in
+            // dev too, and the roots sit outside the workspace fs.allow list.
+            const file = path.resolve(root.dir, rel)
+            if (!file.startsWith(path.resolve(root.dir) + path.sep) || !existsSync(file)) {
+                next()
+                return
+            }
+            const body = readFileSync(file, 'utf-8')
+            res.setHeader('Content-Type', contentTypeFor(file))
+            res.end(root.transform ? root.transform(rel, body) : body)
+        })
+    },
+
+    // After the bundle, so nothing in the pipeline treats these as app assets.
+    closeBundle: {
+        sequential: true,
+        handler() {
+            for (const root of roots) {
+                const dest = path.resolve(this.environment.config.build.outDir, root.urlPath.replace(/^\//, ''))
+                mkdirSync(dest, { recursive: true })
+                if (!root.transform) {
+                    cpSync(root.dir, dest, { recursive: true })
+                    continue
+                }
+                for (const rel of walk(root.dir)) {
+                    const target = path.join(dest, rel)
+                    mkdirSync(path.dirname(target), { recursive: true })
+                    writeFileSync(target, root.transform(rel, readFileSync(path.join(root.dir, rel), 'utf-8')))
+                }
+            }
+        }
+    }
+})