@bndynet/vue-site 0.1.1 → 0.1.3

package/README.md

@@ -67,6 +67,8 @@ Add `"dev": "vue-site dev"` (or `vs dev`) in `package.json` scripts if you like.
 | `links` | Header links: Lucide `icon` + `link`, optional `title` |
 | `packageRepository` | Usually set by CLI from `package.json`; omit when using `createSiteApp` alone |
 | `env` | Dev/build options — see below |
+| `bootstrap` | Optional path from site root (e.g. `./bootstrap.ts`) — module loaded once before the Vue app |
+| `configureApp` | Optional `(app) => void \| Promise<void>` after router install, before `mount` (see [Local packages in `configureApp`](#local-packages-in-configureapp)) |
 
 ### `NavItem`
 
@@ -94,9 +96,36 @@ Add `"dev": "vue-site dev"` (or `vs dev`) in `package.json` scripts if you like.
 | `port` | Dev server port |
 | `outDir` | Build output (relative to site root; default `{folder}-dist`) |
 | `customElements` | Tag prefixes for custom elements (e.g. `['chat-', 'i-']`) |
-| `watchPackages` | Local packages: package name string, or `{ name, entryPath }` for source HMR |
+| `watchPackages` | Local packages — see [env.watchPackages](#envwatchpackages) |
 | `vite` | Vite overrides (not `root`); framework merges aliases, `server.fs.allow`, `build.outDir`, etc. |
 
+### `env.watchPackages`
+
+- **String** — package name only (e.g. workspace symlink / `npm link`). Dependency pre-bundling is skipped; file watching follows Vite defaults.
+- **`{ name, entryPath }`** — `name` must match the import specifier (e.g. `@scope/pkg`). `entryPath` is **relative to the directory where you run the CLI** (the folder that contains `site.config.*`). Vite resolves that package to your **source entry** for dev HMR and adds the package directory to `server.fs.allow`.
+- If you use **`env.vite.resolve.alias` as an array** (`{ find, replacement }[]`), the CLI still merges `watchPackages` aliases correctly (object-only spread would break this).
+- **Do not** add a **top-level value import** of the same package in `site.config.ts` if it is listed here — the config preload runs in Node and would resolve `node_modules`, while the app uses Vite. Use **`configureApp` + dynamic `import()`** instead (see next section).
+
+### Local packages in `configureApp`
+
+`configureApp` may be **`async`** so you can `await import('your-package')` after the router is installed. That dynamic import runs in the browser under Vite, so it respects `watchPackages` and does not run during CLI config loading.
+
+```typescript
+export default defineConfig({
+  env: {
+    watchPackages: [{ name: '@acme/widgets', entryPath: '../widgets/src/index.ts' }],
+  },
+  async configureApp(app) {
+    const w = await import('@acme/widgets')
+    w.register(app)
+  },
+})
+```
+
+### Dev server filesystem access
+
+The CLI allows `server.fs` reads under the site root, the installed `vue-site` package directory, the **parent** of the site root (for `../…` imports), and — when it would not widen to the filesystem root — the **grandparent** (common in monorepos, e.g. `../../packages/...`). Add more paths with `env.vite.server.fs.allow` if needed. Entries from `watchPackages` with `{ entryPath }` also extend `fs.allow` for those package trees.
+
 ## Library mode
 
 Own `index.html` + Vite setup:
@@ -106,9 +135,12 @@ import { createSiteApp } from '@bndynet/vue-site'
 import '@bndynet/vue-site/style.css'
 import config from './site.config'
 
-createSiteApp(config).mount('#app')
+const app = await createSiteApp(config)
+app.mount('#app')
 ```
 
+Use a top-level `await` in your entry (or an async IIFE): `createSiteApp` is async and **awaits** `configureApp` when it returns a `Promise`. If you set optional `bootstrap` in config, that module loads before the app is created; if you omit `bootstrap`, that step is skipped.
+
 Exports: `createSiteApp`, `defineConfig`, `useTheme`, `useSiteConfig`, `themeRefKey`. Types: `SiteConfig`, `SiteEnvConfig`, `SiteViteConfig`, `SiteExternalLink`, `NavItem`, `ThemeConfig`, `ThemeOption`, `ThemePaletteVars`, `ResolvedNavItem`.
 
 ### Theme in Vue pages (`useTheme`)
@@ -151,6 +183,21 @@ npm run dev    # watch-build lib + example site
 npm run build  # `dist/` + `example/example-dist`
 ```
 
+### Using a local build in another project
+
+The published entry points at `dist/`. After changing library **source** under `src/`, run `npm run build:lib` (or `build:lib:watch`) before the consumer sees updates. Changes to **`bin/vue-site.mjs`** apply on the next `vue-site` run without a lib rebuild.
+
+```bash
+cd /path/to/vue-site
+npm install && npm run build:lib
+npm link
+
+cd /path/to/consumer
+npm link @bndynet/vue-site
+```
+
+You do not need to run `npm link` again after editing files; the symlink stays. Use `npm unlink @bndynet/vue-site` and `npm install` in the consumer when done.
+
 ## License
 
 MIT

package/bin/vue-site.mjs

@@ -20,8 +20,29 @@ function resolvePkgDir(pkg) {
 const vuePath = resolvePkgDir('vue')
 const vueRouterPath = resolvePkgDir('vue-router')
 const cwd = process.cwd()
+/** Lets `import('../file.md?raw')` work when `site.config` lives in a subfolder (README next to cwd). In-repo, ../ often falls under pkgDir; from npm install it does not, so we allow cwd's parent explicitly. */
+const cwdParent = resolve(cwd, '..')
+/** Two levels up: monorepos (`apps/docs` importing `../../packages/...`). Omitted when that would be the FS root (too permissive for dev). */
+const cwdGrandparent = resolve(cwd, '../..')
 const command = process.argv[2] || 'dev'
 
+function isLikelyFilesystemRoot(dir) {
+  if (dir === '/' || dir === '//') return true
+  if (process.platform === 'win32') {
+    return /^[a-zA-Z]:[\\/]$/i.test(dir)
+  }
+  return false
+}
+
+const defaultServerFsAllow = [cwd, pkgDir, cwdParent]
+if (
+  cwdGrandparent !== cwdParent &&
+  cwdGrandparent !== cwd &&
+  !isLikelyFilesystemRoot(cwdGrandparent)
+) {
+  defaultServerFsAllow.push(cwdGrandparent)
+}
+
 const configCandidates = [
   'site.config.ts',
   'site.config.js',
@@ -104,7 +125,10 @@ const entryCode = [
   `import '${pkgDir.replace(/\\/g, '/')}/dist/style.css'`,
   `import siteConfig from '/${foundConfig}'`,
   `import { repositoryUrl } from '${VIRTUAL_PACKAGE}'`,
-  `createSiteApp({ ...siteConfig, packageRepository: repositoryUrl }).mount('#app')`,
+  `;(async () => {`,
+  `  const app = await createSiteApp({ ...siteConfig, packageRepository: repositoryUrl })`,
+  `  app.mount('#app')`,
+  `})()`,
 ].join('\n')
 
 const htmlTemplate = `<!DOCTYPE html>
@@ -227,10 +251,16 @@ async function buildViteConfig() {
         watchPatterns.push(`!**/node_modules/${pkg}/**`)
       } else {
         const entryAbs = resolve(cwd, pkg.entryPath)
-        const entryDir = entryAbs.replace(/\/[^/]+$/, '')
+        const entryDir = dirname(entryAbs)
+        if (!fs.existsSync(entryAbs)) {
+          console.warn(
+            `[vue-site] env.watchPackages: entry not found (entryPath is relative to the directory where you run the CLI):\n  ${entryAbs}\n  package: ${pkg.name}`,
+          )
+        }
         excludeNames.push(pkg.name)
         localAliases[pkg.name] = entryAbs
-        watchPatterns.push(`!${entryDir}/**`)
+        const dirForGlob = entryDir.replace(/\\/g, '/')
+        watchPatterns.push(`!${dirForGlob}/**`)
         fsAllowPaths.push(entryDir)
       }
     }
@@ -253,9 +283,22 @@ async function buildViteConfig() {
       },
     }
     if (Object.keys(localAliases).length) {
+      const prevAlias = userViteRest.resolve?.alias
+      const extraPairs = Object.entries(localAliases).map(([find, replacement]) => ({
+        find,
+        replacement,
+      }))
+      let mergedAlias
+      if (prevAlias == null) {
+        mergedAlias = { ...localAliases }
+      } else if (Array.isArray(prevAlias)) {
+        mergedAlias = [...prevAlias, ...extraPairs]
+      } else {
+        mergedAlias = { ...prevAlias, ...localAliases }
+      }
       userViteRest.resolve = {
         ...userViteRest.resolve,
-        alias: { ...userViteRest.resolve?.alias, ...localAliases },
+        alias: mergedAlias,
       }
     }
     if (fsAllowPaths.length) {
@@ -285,7 +328,7 @@ async function buildViteConfig() {
       open: true,
       ...(port != null && { port }),
       fs: {
-        allow: [cwd, pkgDir],
+        allow: defaultServerFsAllow,
       },
     },
     build: {
@@ -324,7 +367,10 @@ import { createSiteApp } from '${pkgDir.replace(/\\/g, '/')}/dist/index.es.js'
 import '${pkgDir.replace(/\\/g, '/')}/dist/style.css'
 import siteConfig from './${foundConfig}'
 import { repositoryUrl } from '${VIRTUAL_PACKAGE}'
-createSiteApp({ ...siteConfig, packageRepository: repositoryUrl }).mount('#app')
+;(async () => {
+  const app = await createSiteApp({ ...siteConfig, packageRepository: repositoryUrl })
+  app.mount('#app')
+})()
   </script>
 </body>
 </html>`

package/dist/create-app.d.ts

@@ -1,2 +1,2 @@
 import { SiteConfig } from './types';
-export declare function createSiteApp(config: SiteConfig): import('vue').App<Element>;
+export declare function createSiteApp(config: SiteConfig): Promise<import('vue').App<Element>>;

package/dist/index.es.js

@@ -38128,8 +38128,18 @@ const CS = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
     };
   }
 });
-function pA(e) {
+function lA(e) {
+  const a = e.trim();
+  if (!a) throw new Error("[vue-site] bootstrap path is empty");
+  return a.startsWith("/") ? a : "/" + a.replace(/^\.\//, "");
+}
+async function sA(e) {
+  if (e.bootstrap == null || String(e.bootstrap).trim() === "") return;
+  await import(lA(String(e.bootstrap)));
+}
+async function fA(e) {
   var d, h, s, y;
+  await sA(e);
   const a = GI(e.nav), c = fS(a), o = ["light", "dark", ...((h = (d = e.theme) == null ? void 0 : d.extraThemes) == null ? void 0 : h.filter((f) => f.id !== "light" && f.id !== "dark").map((f) => f.id)) ?? []], i = bS(e.theme), u = me("light");
   mS(
     u,
@@ -38139,15 +38149,15 @@ function pA(e) {
     (y = e.theme) == null ? void 0 : y.colors
   ), document.title = e.title;
   const r = tL(hA);
-  return r.provide(XI, u), r.provide(dI, { config: e, resolvedNav: a }), r.use(c), r;
+  return r.provide(XI, u), r.provide(dI, { config: e, resolvedNav: a }), r.use(c), e.configureApp && await Promise.resolve(e.configureApp(r)), r;
 }
-function kA(e) {
+function MA(e) {
   return e;
 }
 export {
   eI as builtinThemePalettes,
-  pA as createSiteApp,
-  kA as defineConfig,
+  fA as createSiteApp,
+  MA as defineConfig,
   XI as themeRefKey,
   Rt as useSiteConfig,
   xS as useTheme

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import { Component } from 'vue';
+import { App, Component } from 'vue';
 import { UserConfig as ViteUserConfig } from 'vite';
 export interface NavItem {
     label: string;
@@ -65,7 +65,7 @@ export interface SiteEnvConfig {
     /**
      * Local packages to watch for source changes and exclude from pre-bundling.
      * - `string` -- symlinked package name (npm workspaces / npm link)
-     * - `{ name, entryPath }` -- resolve imports to a source entry file so Vite compiles it directly (e.g. `'../my-lib/src/index.ts'`)
+     * - `{ name, entryPath }` -- resolve imports to a source entry file so Vite compiles it directly; `entryPath` is relative to the directory where you run `vue-site` (the folder that contains `site.config.*`)
      */
     watchPackages?: (string | {
         name: string;
@@ -97,6 +97,19 @@ export interface SiteConfig {
     packageRepository?: string | null;
     /** Development / build environment configuration */
     env?: SiteEnvConfig;
+    /**
+     * Optional. Path to a module under the site root (Vite `root`), loaded once **before** the Vue app
+     * is created. Omit or leave unset to skip. Use for global side effects (polyfills, telemetry,
+     * `window` setup). Relative to root, e.g. `./bootstrap.ts` or `src/bootstrap.ts` (resolved as
+     * `/bootstrap.ts`, `/src/bootstrap.ts`).
+     */
+    bootstrap?: string;
+    /**
+     * Called after the app is created, context is provided, and the router is installed — before
+     * `createSiteApp` resolves (call `.mount()` after `await`). Use for `app.use()`, global directives, etc.
+     * May return a Promise (e.g. after `await import()` of a package listed in `env.watchPackages`).
+     */
+    configureApp?: (app: App) => void | Promise<void>;
 }
 export interface ResolvedNavItem extends NavItem {
     resolvedPath: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bndynet/vue-site",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "description": "A configurable Vue 3 site framework with sidebar navigation, markdown rendering, and theme switching.",
   "repository": {
@@ -50,7 +50,6 @@
   },
   "devDependencies": {
     "@types/markdown-it": "^14.1.0",
-    "concurrently": "^9.2.1",
     "rimraf": "^6.1.3",
     "typescript": "~5.7.0",
     "vite-plugin-dts": "^4.5.0",