@bndynet/vue-site 0.1.2 → 0.1.3

package/README.md

@@ -68,7 +68,7 @@ Add `"dev": "vue-site dev"` (or `vs dev`) in `package.json` scripts if you like.
 | `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` after router install, before `mount` |
+| `configureApp` | Optional `(app) => void \| Promise<void>` after router install, before `mount` (see [Local packages in `configureApp`](#local-packages-in-configureapp)) |
 
 ### `NavItem`
 
@@ -96,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:
@@ -112,7 +139,7 @@ const app = await createSiteApp(config)
 app.mount('#app')
 ```
 
-Use a top-level `await` in your entry (or an async IIFE): `createSiteApp` is async. If you set optional `bootstrap` in config, that module loads before the app is created; if you omit `bootstrap`, that step is skipped.
+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`.
 
@@ -156,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',
@@ -230,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)
       }
     }
@@ -256,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) {
@@ -288,7 +328,7 @@ async function buildViteConfig() {
       open: true,
       ...(port != null && { port }),
       fs: {
-        allow: [cwd, pkgDir],
+        allow: defaultServerFsAllow,
       },
     },
     build: {

package/dist/index.es.js

@@ -38138,9 +38138,9 @@ async function sA(e) {
   await import(lA(String(e.bootstrap)));
 }
 async function fA(e) {
-  var d, h, s, y, f;
+  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((k) => k.id !== "light" && k.id !== "dark").map((k) => k.id)) ?? []], i = bS(e.theme), u = me("light");
+  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,
     ((s = e.theme) == null ? void 0 : s.default) ?? "light",
@@ -38149,7 +38149,7 @@ async function fA(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), (f = e.configureApp) == null || f.call(e, r), 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 MA(e) {
   return e;

package/dist/types.d.ts

@@ -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;
@@ -107,8 +107,9 @@ export interface SiteConfig {
     /**
      * 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;
+    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.2",
+  "version": "0.1.3",
   "type": "module",
   "description": "A configurable Vue 3 site framework with sidebar navigation, markdown rendering, and theme switching.",
   "repository": {