@bndynet/vue-site 0.1.2 → 0.1.4

package/README.md

@@ -50,6 +50,14 @@ npx vue-site build
 npx vue-site preview
 ```
 
+Subpath deploy: pass Vite’s public base on the CLI (overrides `env.vite.base` in `site.config`):
+
+```bash
+npx vue-site build --base=/app/
+# or
+npx vue-site build --base /app/
+```
+
 Add `"dev": "vue-site dev"` (or `vs dev`) in `package.json` scripts if you like.
 
 ## Config reference
@@ -68,7 +76,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 +104,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 +147,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 +191,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,7 +20,66 @@ function resolvePkgDir(pkg) {
 const vuePath = resolvePkgDir('vue')
 const vueRouterPath = resolvePkgDir('vue-router')
 const cwd = process.cwd()
-const command = process.argv[2] || 'dev'
+/** 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, '../..')
+
+/**
+ * @param {string[]} argv
+ * @returns {{ command: string, cliBase?: string }}
+ */
+function parseCliArgv(argv = process.argv) {
+  const sub = argv[2]
+  const command =
+    sub && !sub.startsWith('-')
+      ? sub
+      : 'dev'
+
+  let cliBase
+  const flagStart = command === sub && sub ? 3 : 2
+  for (let i = flagStart; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--base') {
+      const v = argv[i + 1]
+      if (!v || v.startsWith('-')) {
+        console.error(
+          '[vue-site] --base requires a value (e.g. --base=/app/ or --base /app/)',
+        )
+        process.exit(1)
+      }
+      cliBase = v
+      i++
+    } else if (a.startsWith('--base=')) {
+      const v = a.slice('--base='.length)
+      if (!v) {
+        console.error(
+          '[vue-site] --base= requires a value (e.g. --base=/app/)',
+        )
+        process.exit(1)
+      }
+      cliBase = v
+    }
+  }
+  return { command, cliBase }
+}
+
+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',
@@ -194,15 +253,20 @@ function vueSitePlugin() {
   ]
 }
 
-async function buildViteConfig() {
+async function buildViteConfig(options = {}) {
+  const { cliBase } = options
   const siteConfig = await loadSiteConfig()
+  const env = siteConfig.env || {}
   const {
     port,
     outDir,
     customElements = [],
-    watchPackages = [],
     vite: userVite = {},
-  } = siteConfig.env || {}
+  } = env
+  const watchPackages =
+    env.watchPackages !== undefined
+      ? env.watchPackages
+      : siteConfig.watchPackages ?? []
   const { vue: userVueOpts = {}, plugins: userPlugins, ...userViteRest } =
     userVite
 
@@ -230,10 +294,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 +326,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,20 +371,22 @@ async function buildViteConfig() {
       open: true,
       ...(port != null && { port }),
       fs: {
-        allow: [cwd, pkgDir],
+        allow: defaultServerFsAllow,
       },
     },
     build: {
       outDir: resolve(cwd, outDir || `${basename(cwd)}-dist`),
       emptyOutDir: true,
     },
+    ...(cliBase != null && { base: cliBase }),
   }
 
   return mergeConfig(userViteRest, baseConfig)
 }
 
 async function run() {
-  const viteConfig = await buildViteConfig()
+  const { command, cliBase } = parseCliArgv()
+  const viteConfig = await buildViteConfig({ cliBase })
 
   if (command === 'dev') {
     const server = await createServer(viteConfig)
@@ -350,7 +435,10 @@ import { repositoryUrl } from '${VIRTUAL_PACKAGE}'
     )
     server.printUrls()
   } else {
-    console.log('Usage: vue-site|vs <dev|build|preview>')
+    console.log(
+      'Usage: vue-site|vs <dev|build|preview> [--base=<path>]\n' +
+        '  --base   Public path for assets (overrides env.vite.base); e.g. --base=/app/',
+    )
     process.exit(1)
   }
 }

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.4",
   "type": "module",
   "description": "A configurable Vue 3 site framework with sidebar navigation, markdown rendering, and theme switching.",
   "repository": {