@greendrake/vite-preset 0.5.0 → 0.7.0

package/README.md

@@ -34,12 +34,13 @@ export default defineConfig(
 | `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). |
+| `htmlData` | JSON data elements written into `index.html`, by element id, for the app to read at runtime (see `htmlData` below). |
 | `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` and `htmlPlaceholders` plugins when their options are given;
+- plugins: `@vitejs/plugin-vue` and the HMR circular-import guard, plus the `staticRoots`, `htmlPlaceholders` and `htmlData` 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;
@@ -87,6 +88,10 @@ import { loadAppEnv, requirePort, envBool, deriveImageBaseUrl, apiTargetEnv, bui
 
 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.
 
+### `htmlData(map)`
+
+Writes `<script type="application/json" id="<id>">JSON</script>` into the head of `index.html` per entry — settings the app reads at runtime (`JSON.parse` of the element's text) rather than through a compile-time define. `<` in the JSON is escaped, so no value ends the element. A `null` value leaves the element empty for a Go binary that serves the build to fill from its own configuration: `greendrake/spa`'s `Data` matches the element in exactly this form. `vueSpa`'s `htmlData` option installs it.
+
 ### `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.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@greendrake/vite-preset",
-    "version": "0.5.0",
+    "version": "0.7.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>",
@@ -44,7 +44,7 @@
         "vite": ">=8"
     },
     "devDependencies": {
-        "@greendrake/dev-config": "0.5.0",
+        "@greendrake/dev-config": "0.7.0",
         "@types/bun": "^1.3.5",
         "@types/node": "^24.0.0",
         "typescript": "6.0.3",

package/src/html.ts

@@ -1,5 +1,22 @@
 import type { Plugin } from 'vite'
 
+// Writes a data element per entry into index.html's head —
+// <script type="application/json" id="<id>">JSON</script> — that the app
+// reads at runtime instead of a compile-time define. A null value leaves the
+// element empty, for the Go binary that serves the build to fill
+// (greendrake/spa's Data, which matches the element in exactly this form).
+// `<` is escaped so no value can end the script element.
+export const htmlData = (map: Record<string, unknown>): Plugin => ({
+    name: 'greendrake-html-data',
+    transformIndexHtml: () =>
+        Object.entries(map).map(([id, value]) => ({
+            tag: 'script',
+            attrs: { type: 'application/json', id },
+            children: value === null ? '' : JSON.stringify(value).replace(/</g, '\\u003c'),
+            injectTo: 'head-prepend' as const
+        }))
+})
+
 // 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__).

package/src/main.ts

@@ -8,11 +8,11 @@ export { envBool, deriveImageBaseUrl, loadAppEnv, requirePort, apiTargetEnv, bui
 // 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 } from './html'
+export { htmlData, htmlPlaceholders } 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 } from './html'
+import { htmlData, htmlPlaceholders } from './html'
 import { hmrCircularImportGuard } from './hmr'
 import { nestedDependencies, type DeclaredDependencies } from './sourceDeps'
 import { staticRoots as staticRootsPlugin, type StaticRoot } from './staticRoots'
@@ -34,6 +34,9 @@ export interface VueSpaOptions {
     // Build-time placeholder substitution in index.html (see the
     // htmlPlaceholders plugin) — e.g. injecting an inline bootstrap script.
     htmlPlaceholders?: Record<string, string>
+    // Data elements in index.html the app reads at runtime, by element id
+    // (see the htmlData plugin).
+    htmlData?: Record<string, unknown> | undefined
     // 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
@@ -88,7 +91,13 @@ export const vueSpa =
         const portPin = command === 'serve' && options.port !== false ? { port: typeof options.port === 'number' ? options.port : requirePort(), strictPort: true } : undefined
         const base: UserConfig = {
             ...(options.define && { 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)] : [])],
+            plugins: [
+                vue(),
+                hmrCircularImportGuard(),
+                ...(options.staticRoots?.length ? [staticRootsPlugin(options.staticRoots)] : []),
+                ...(options.htmlPlaceholders ? [htmlPlaceholders(options.htmlPlaceholders)] : []),
+                ...(options.htmlData ? [htmlData(options.htmlData)] : [])
+            ],
             ...(command === 'serve'
                 ? {
                       server: {

package/src/staticRoots.ts

@@ -25,17 +25,24 @@ const contentTypeFor = (file: string): string => {
     return 'text/plain; charset=utf-8'
 }
 
-// Every file under dir, as paths relative to it.
+// What a root publishes: every file under it that is not a dotfile, nor under
+// a dot-directory. A dotfile is never a product asset — it is what Finder
+// (.DS_Store) and editors leave in a directory uninvited — and published it
+// would be served as one, or handed to the transform and parsed as a catalogue.
+// Split on either separator: the dev middleware passes URL paths.
+const published = (relativePath: string): boolean => !relativePath.split(/[\\/]/).some(segment => segment.startsWith('.'))
+
+// Every published 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)))
+        .filter(published)
 
 // 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 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',
@@ -52,7 +59,7 @@ export const staticRoots = (roots: StaticRoot[]): Plugin => ({
             // 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)) {
+            if (!published(rel) || !file.startsWith(path.resolve(root.dir) + path.sep) || !existsSync(file)) {
                 next()
                 return
             }
@@ -70,7 +77,7 @@ export const staticRoots = (roots: StaticRoot[]): Plugin => ({
                 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 })
+                    cpSync(root.dir, dest, { recursive: true, filter: source => published(path.relative(root.dir, source)) })
                     continue
                 }
                 for (const rel of walk(root.dir)) {