@bndynet/vue-site 1.3.2 → 1.4.1

package/README.md

@@ -23,6 +23,15 @@ Configurable Vue 3 site framework: one package, `site.config.ts`, and Markdown p
 npm install @bndynet/vue-site
 ```
 
+Create starter files in the current directory:
+
+```bash
+npx vue-site init
+```
+
+This creates `site.config.ts`, `env.d.ts`, and `README.md`. Existing files are never overwritten.
+You can also create the configuration manually:
+
 **`site.config.ts`**
 
 ```typescript
@@ -44,6 +53,7 @@ export default defineConfig({
 my-site/
   package.json
   site.config.ts
+  env.d.ts
   public/favicon.ico
   README.md
   pages/guide.md
@@ -52,15 +62,32 @@ my-site/
 **CLI** (`vue-site` and `vs` are the same)
 
 ```bash
+npx vue-site init
 npx vue-site dev
 npx vue-site build
 npx vue-site preview
 ```
 
+`init` is safe to run more than once: it creates only missing starter files and leaves existing
+configuration, type declarations, and README content unchanged.
+
+Use a different config for an environment with `--config` / `-c`. The selected file must live in
+the current site root and may use the `.ts`, `.js`, `.mts`, or `.mjs` extension. `dev`, `build`, and
+`preview` all support the option:
+
+```bash
+npx vue-site dev --config site.config.dev.ts
+npx vue-site build --config site.config.prod.ts
+npx vue-site preview -c site.config.prod.ts
+```
+
+When `--config` is omitted, the CLI keeps auto-discovering `site.config.ts`, `site.config.js`,
+`site.config.mts`, or `site.config.mjs` in that order.
+
 Subpath deploy: pass Vite’s public base on the CLI (overrides `env.vite.base` in `site.config`):
 
 ```bash
-npx vue-site build --base=/app/
+npx vue-site build --config site.config.prod.ts --base=/app/
 # or
 npx vue-site build --base /app/
 ```
@@ -90,10 +117,67 @@ Add `"dev": "vue-site dev"` (or `vs dev`) in `package.json` scripts if you like.
 | `auth` | Central authorization policy (`AuthConfig`) — see [Per-page authorization](#per-page-authorization-auth) |
 | `router` | History mode (`RouterConfig`) — `hash` (default) or HTML5 `web`; see [Router history](#router-history-router) |
 | `packageRepository` | Usually set by CLI from `package.json`; omit when using `createSiteApp` alone |
+| `custom` | Public application-specific values, available from `useSiteConfig().config.custom`; see [Custom client configuration](#custom-client-configuration-custom) |
 | `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)) |
 
+### Custom client configuration (`custom`)
+
+Use `custom` for public, application-specific values that the framework should preserve without
+interpreting. They are available to every component through `useSiteConfig()`:
+
+```typescript
+// site.config.ts
+export default defineConfig({
+  title: 'My Site',
+  nav: [/* ... */],
+  custom: {
+    apiBaseUrl: 'http://localhost/api/v1',
+  },
+})
+```
+
+```typescript
+// Inside a Vue component
+const { config } = useSiteConfig()
+const apiBaseUrl = config.custom?.apiBaseUrl
+```
+
+Use a different config file when the value changes between builds:
+
+```typescript
+// site.config.prod.ts
+export default defineConfig({
+  title: 'My Site',
+  nav: [/* ... */],
+  custom: {
+    apiBaseUrl: 'https://prod.com/api/v1',
+  },
+})
+```
+
+```bash
+npx vue-site build --config site.config.prod.ts
+```
+
+`custom` is typed as `SiteCustomConfig`. Application-specific keys can be made type-safe with
+module augmentation:
+
+```typescript
+// site-custom.d.ts
+import '@bndynet/vue-site'
+
+declare module '@bndynet/vue-site' {
+  interface SiteCustomConfig {
+    apiBaseUrl: string
+  }
+}
+```
+
+All `custom` values are bundled into client code and are visible to users. Never store passwords,
+tokens, private keys, or other secrets in this field.
+
 ### `NavItem`
 
 | Property | Description |
@@ -454,7 +538,7 @@ export default defineConfig({
 
 - `authorize` runs **on every navigation** (a Vue Router `beforeEach` guard). It receives `{ rule, item, to, from }` and returns `true` (allow), `false` (deny), or a path `string` (redirect, e.g. to a login page).
 - On `false`, the user is sent to `auth.loginPath` with the requested path as a `redirect` query (`/login?redirect=/admin`); if `loginPath` is unset, the navigation is cancelled.
-- `authorize` also runs **once at startup** (with only `rule` / `item`) to hide unauthorized items from the nav menu. Like `visible`, this menu filtering is not reactive — it reflects the state at app creation, so update it by recreating the app (e.g. a full reload after login).
+- `authorize` also runs when the auth-filtered nav menu is refreshed (with only `rule` / `item`) to hide unauthorized items from the nav menu. The framework refreshes this menu after navigations; after changing auth state without a navigation, call `useSiteConfig().refreshAuthNav()`.
 - Guarded routes stay **registered**, so visiting a protected URL directly triggers the guard (and your login redirect) rather than silently 404-ing.
 - The login page itself must **not** carry an `auth` rule (and `loginPath` is always allowed by the guard) to avoid redirect loops.
 
@@ -472,9 +556,9 @@ export default defineConfig({
 | | `visible` | `auth` |
 |--|-----------|--------|
 | Decides | Whether the item/route **exists** | Whether the **current user** may enter |
-| When | Build/startup (once) | Navigation (every time) + startup for menu filtering |
+| When | Build/startup (once) | Navigation (every time) + refreshed menu filtering |
 | Route registered | No (unreachable by URL) | Yes (guarded; can redirect to login) |
-| Reacts to login/logout | No | Guard yes; menu filtering no |
+| Reacts to login/logout | No | Guard yes; menu filtering yes after navigation or `refreshAuthNav()` |
 | Best for | Env / feature-flag / static trimming | Login state, roles, login redirects |
 
 Use `visible` for static existence trimming and `auth` for user-based access. They can be combined on the same item.
@@ -555,7 +639,7 @@ 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`, `useLocale`, `useLocalize`, `tk`, `resolveLocalized`, `resolveField`, `resolveMessage`, `mergeCatalog`, `flattenMessages`, `isMessageRef`, `localizedPage`, `builtinMessages`, `themeRefKey`, `localeRefKey`. Types: `SiteConfig`, `SiteEnvConfig`, `SiteViteConfig`, `SiteExternalLink`, `ShellConfig`, `ShellAction`, `ShellActionLoader`, `NavItem`, `StandalonePage`, `PageLayout`, `AuthRule`, `AuthContext`, `AuthConfig`, `RouterConfig`, `ThemeConfig`, `ThemeOption`, `ThemePaletteVars`, `ResolvedNavItem`, `I18nConfig`, `LocaleOption`, `LocaleCode`, `LocalizedString`, `IconRegistry`, `MessageRef`, `MessageTree`, `MessageCatalog`, `PageLoader`, `LocalizedPageOptions`.
+Exports: `createSiteApp`, `defineConfig`, `useTheme`, `useSiteConfig`, `useLocale`, `useLocalize`, `tk`, `resolveLocalized`, `resolveField`, `resolveMessage`, `mergeCatalog`, `flattenMessages`, `isMessageRef`, `localizedPage`, `builtinMessages`, `themeRefKey`, `localeRefKey`. Types: `SiteConfig`, `SiteEnvConfig`, `SiteViteConfig`, `SiteCustomConfig`, `SiteExternalLink`, `ShellConfig`, `ShellAction`, `ShellActionLoader`, `NavItem`, `StandalonePage`, `PageLayout`, `AuthRule`, `AuthContext`, `AuthConfig`, `RouterConfig`, `ThemeConfig`, `ThemeOption`, `ThemePaletteVars`, `ResolvedNavItem`, `I18nConfig`, `LocaleOption`, `LocaleCode`, `LocalizedString`, `IconRegistry`, `MessageRef`, `MessageTree`, `MessageCatalog`, `PageLoader`, `LocalizedPageOptions`.
 
 ### Theme in Vue pages (`useTheme`)
 

package/README.zh.md

@@ -22,6 +22,15 @@
 npm install @bndynet/vue-site
 ```
 
+在当前目录创建初始文件：
+
+```bash
+npx vue-site init
+```
+
+该命令会创建 `site.config.ts`、`env.d.ts` 和 `README.md`，绝不会覆盖已有文件。
+也可以手动创建配置：
+
 **`site.config.ts`**
 
 ```typescript
@@ -43,6 +52,7 @@ export default defineConfig({
 my-site/
   package.json
   site.config.ts
+  env.d.ts
   public/favicon.ico
   README.md
   pages/guide.md
@@ -51,15 +61,30 @@ my-site/
 **CLI**（`vue-site` 与 `vs` 等价）
 
 ```bash
+npx vue-site init
 npx vue-site dev
 npx vue-site build
 npx vue-site preview
 ```
 
+`init` 可以安全地重复执行：它只创建缺失的初始文件，不会改动已有配置、类型声明或 README。
+
+可以通过 `--config` / `-c` 为不同环境选择配置文件。指定的文件必须直接位于当前站点根目录，
+扩展名可以是 `.ts`、`.js`、`.mts` 或 `.mjs`；`dev`、`build`、`preview` 都支持该参数：
+
+```bash
+npx vue-site dev --config site.config.dev.ts
+npx vue-site build --config site.config.prod.ts
+npx vue-site preview -c site.config.prod.ts
+```
+
+省略 `--config` 时，CLI 仍会依次自动查找 `site.config.ts`、`site.config.js`、
+`site.config.mts`、`site.config.mjs`。
+
 子路径部署：在 CLI 上传入 Vite 的公共 base（会覆盖 `site.config` 中的 `env.vite.base`）：
 
 ```bash
-npx vue-site build --base=/app/
+npx vue-site build --config site.config.prod.ts --base=/app/
 # 或
 npx vue-site build --base /app/
 ```
@@ -87,10 +112,65 @@ npx vue-site build --base /app/
 | `auth` | 中心化的授权策略（`AuthConfig`）—— 参见[按页面授权](#按页面授权-auth) |
 | `router` | 历史模式（`RouterConfig`）—— `hash`（默认）或 HTML5 `web`；参见[路由历史](#路由历史-router) |
 | `packageRepository` | 通常由 CLI 从 `package.json` 设置；单独使用 `createSiteApp` 时可省略 |
+| `custom` | 公开的业务自定义配置，可通过 `useSiteConfig().config.custom` 读取；参见[自定义客户端配置](#自定义客户端配置-custom) |
 | `env` | 开发/构建选项 —— 见下文 |
 | `bootstrap` | 可选的站点根目录相对路径（如 `./bootstrap.ts`）—— 在 Vue 应用之前加载一次的模块 |
 | `configureApp` | 可选的 `(app) => void \| Promise<void>`，在路由安装之后、`mount` 之前执行（参见 [`configureApp` 中的本地包](#在-configureapp-中使用本地包)） |
 
+### 自定义客户端配置（`custom`）
+
+`custom` 用于存放框架无需解释、只需原样保留的公开业务配置。任何组件都可以通过
+`useSiteConfig()` 读取：
+
+```typescript
+// site.config.ts
+export default defineConfig({
+  title: '我的站点',
+  nav: [/* ... */],
+  custom: {
+    apiBaseUrl: 'http://localhost/api/v1',
+  },
+})
+```
+
+```typescript
+// Vue 组件中
+const { config } = useSiteConfig()
+const apiBaseUrl = config.custom?.apiBaseUrl
+```
+
+如果不同构建环境使用不同的值，可以选择不同的配置文件：
+
+```typescript
+// site.config.prod.ts
+export default defineConfig({
+  title: '我的站点',
+  nav: [/* ... */],
+  custom: {
+    apiBaseUrl: 'https://prod.com/api/v1',
+  },
+})
+```
+
+```bash
+npx vue-site build --config site.config.prod.ts
+```
+
+`custom` 的类型是 `SiteCustomConfig`。可以通过模块扩充为业务字段提供强类型：
+
+```typescript
+// site-custom.d.ts
+import '@bndynet/vue-site'
+
+declare module '@bndynet/vue-site' {
+  interface SiteCustomConfig {
+    apiBaseUrl: string
+  }
+}
+```
+
+所有 `custom` 值都会进入客户端代码，用户可以查看。不要在这里存放密码、Token、私钥或其他密钥。
+
 ### `NavItem`
 
 | 属性 | 说明 |
@@ -378,9 +458,9 @@ export default defineConfig({
   并返回 `true`（允许）、`false`（拒绝）或一个路径 `string`（重定向，例如到登录页）。
 - 返回 `false` 时，用户会被发送到 `auth.loginPath`，并把请求的路径作为 `redirect` 查询参数
   （`/login?redirect=/admin`）；如果未设置 `loginPath`，则取消该次导航。
-- `authorize` 也会在**启动时运行一次**（仅带 `rule` / `item`），以从导航菜单中隐藏未授权的条目。
-  与 `visible` 一样，此菜单过滤不具响应性 —— 它反映应用创建时的状态，因此需要通过重建应用来更新它
-  （例如登录后整页刷新）。
+- `authorize` 也会在 auth 过滤后的导航菜单刷新时运行（仅带 `rule` / `item`），以从导航菜单中隐藏未授权的条目。
+  框架会在导航完成后刷新此菜单；如果你在没有导航的情况下改变登录状态，请调用
+  `useSiteConfig().refreshAuthNav()`。
 - 受保护的路由仍保持**注册**，因此直接访问受保护 URL 会触发守卫（及你的登录重定向），
   而不是静默地 404。
 - 登录页本身**不能**携带 `auth` 规则（且 `loginPath` 始终被守卫允许），以避免重定向循环。
@@ -400,9 +480,9 @@ export default defineConfig({
 | | `visible` | `auth` |
 |--|-----------|--------|
 | 决定 | 条目/路由是否**存在** | **当前用户**是否可以进入 |
-| 时机 | 构建/启动（一次） | 导航（每次）+ 启动时的菜单过滤 |
+| 时机 | 构建/启动（一次） | 导航（每次）+ 刷新时的菜单过滤 |
 | 路由是否注册 | 否（无法通过 URL 访问） | 是（受守卫保护；可重定向到登录） |
-| 对登录/登出的响应 | 否 | 守卫：是；菜单过滤：否 |
+| 对登录/登出的响应 | 否 | 守卫：是；菜单过滤：导航后或 `refreshAuthNav()` 后是 |
 | 最适合 | 环境 / 功能开关 / 静态裁剪 | 登录状态、角色、登录重定向 |
 
 用 `visible` 进行静态存在性裁剪，用 `auth` 进行基于用户的访问控制。它们可以组合在同一个条目上。
@@ -497,7 +577,7 @@ app.mount('#app')
 返回 `Promise` 时会 **await** 它。如果你在配置中设置了可选的 `bootstrap`，该模块会在应用创建前加载；
 如果省略 `bootstrap`，则跳过该步骤。
 
-导出：`createSiteApp`、`defineConfig`、`useTheme`、`useSiteConfig`、`useLocale`、`useLocalize`、`tk`、`resolveLocalized`、`resolveField`、`resolveMessage`、`mergeCatalog`、`flattenMessages`、`isMessageRef`、`localizedPage`、`builtinMessages`、`themeRefKey`、`localeRefKey`。类型：`SiteConfig`、`SiteEnvConfig`、`SiteViteConfig`、`SiteExternalLink`、`NavItem`、`StandalonePage`、`PageLayout`、`AuthRule`、`AuthContext`、`AuthConfig`、`RouterConfig`、`ThemeConfig`、`ThemeOption`、`ThemePaletteVars`、`ResolvedNavItem`、`I18nConfig`、`LocaleOption`、`LocaleCode`、`LocalizedString`、`MessageRef`、`MessageTree`、`MessageCatalog`、`PageLoader`、`LocalizedPageOptions`。
+导出：`createSiteApp`、`defineConfig`、`useTheme`、`useSiteConfig`、`useLocale`、`useLocalize`、`tk`、`resolveLocalized`、`resolveField`、`resolveMessage`、`mergeCatalog`、`flattenMessages`、`isMessageRef`、`localizedPage`、`builtinMessages`、`themeRefKey`、`localeRefKey`。类型：`SiteConfig`、`SiteEnvConfig`、`SiteViteConfig`、`SiteCustomConfig`、`SiteExternalLink`、`NavItem`、`StandalonePage`、`PageLayout`、`AuthRule`、`AuthContext`、`AuthConfig`、`RouterConfig`、`ThemeConfig`、`ThemeOption`、`ThemePaletteVars`、`ResolvedNavItem`、`I18nConfig`、`LocaleOption`、`LocaleCode`、`LocalizedString`、`MessageRef`、`MessageTree`、`MessageCatalog`、`PageLoader`、`LocalizedPageOptions`。
 
 ### 在 Vue 页面中使用主题（`useTheme`）
 

package/bin/vue-site.mjs

@@ -45,7 +45,7 @@ const cwdGrandparent = resolve(cwd, '../..')
 
 /**
  * @param {string[]} argv
- * @returns {{ command: string, cliBase?: string }}
+ * @returns {{ command: string, cliBase?: string, cliConfig?: string }}
  */
 function parseCliArgv(argv = process.argv) {
   const sub = argv[2]
@@ -55,6 +55,7 @@ function parseCliArgv(argv = process.argv) {
       : 'dev'
 
   let cliBase
+  let cliConfig
   const flagStart = command === sub && sub ? 3 : 2
   for (let i = flagStart; i < argv.length; i++) {
     const a = argv[i]
@@ -77,9 +78,28 @@ function parseCliArgv(argv = process.argv) {
         process.exit(1)
       }
       cliBase = v
+    } else if (a === '--config' || a === '-c') {
+      const v = argv[i + 1]
+      if (!v || v.startsWith('-')) {
+        console.error(
+          '[vue-site] --config requires a value (e.g. --config site.config.prod.ts)',
+        )
+        process.exit(1)
+      }
+      cliConfig = v
+      i++
+    } else if (a.startsWith('--config=')) {
+      const v = a.slice('--config='.length)
+      if (!v) {
+        console.error(
+          '[vue-site] --config= requires a value (e.g. --config=site.config.prod.ts)',
+        )
+        process.exit(1)
+      }
+      cliConfig = v
     }
   }
-  return { command, cliBase }
+  return { command, cliBase, cliConfig }
 }
 
 function isLikelyFilesystemRoot(dir) {
@@ -105,20 +125,114 @@ const configCandidates = [
   'site.config.mts',
   'site.config.mjs',
 ]
-const foundConfig = configCandidates.find((f) => fs.existsSync(resolve(cwd, f)))
-if (!foundConfig) {
-  console.error(
+
+const initSiteConfig = `import { defineConfig } from '@bndynet/vue-site'
+
+export default defineConfig({
+  title: 'My Site',
+  // Public client configuration. Never place secrets here.
+  custom: {
+    // apiBaseUrl: 'http://localhost/api/v1',
+  },
+  nav: [
+    { label: 'Home', icon: 'home', page: './README.md' },
+  ],
+})
+`
+
+const initEnvTypes = `/// <reference types="vite/client" />
+
+import '@bndynet/vue-site'
+
+declare module '@bndynet/vue-site' {
+  interface SiteCustomConfig {
+    // apiBaseUrl: string
+  }
+}
+`
+
+const initReadme = `# My Site
+
+Welcome to your vue-site project.
+`
+
+class CliConfigError extends Error {}
+
+function createInitFile(name, contents) {
+  const filePath = resolve(cwd, name)
+  try {
+    fs.writeFileSync(filePath, contents, { flag: 'wx' })
+    console.log(`  created ${name}`)
+    return true
+  } catch (e) {
+    if (e && typeof e === 'object' && e.code === 'EEXIST') {
+      console.log(`  skipped ${name} (already exists)`)
+      return false
+    }
+    throw e
+  }
+}
+
+function initSite() {
+  console.log('[vue-site] Initializing site files:')
+
+  let created = 0
+  const existingConfig = configCandidates.find((file) =>
+    fs.existsSync(resolve(cwd, file)),
+  )
+
+  if (existingConfig) {
+    console.log(`  skipped site.config.ts (${existingConfig} already exists)`)
+  } else if (createInitFile('site.config.ts', initSiteConfig)) {
+    created++
+  }
+
+  if (createInitFile('env.d.ts', initEnvTypes)) created++
+  if (createInitFile('README.md', initReadme)) created++
+
+  console.log(
+    created > 0
+      ? `\n[vue-site] Created ${created} file${created === 1 ? '' : 's'}. Run \`npx vue-site dev\` to start.`
+      : '\n[vue-site] Nothing to create; existing files were left unchanged.',
+  )
+}
+
+function resolveSiteConfig(cliConfig) {
+  if (cliConfig) {
+    const configPath = resolve(cwd, cliConfig)
+    if (dirname(configPath) !== cwd) {
+      throw new CliConfigError(
+        `[vue-site] --config must name a file in the site root (${cwd}): ${cliConfig}`,
+      )
+    }
+    if (!/\.(?:ts|js|mts|mjs)$/.test(configPath)) {
+      throw new CliConfigError(
+        `[vue-site] Unsupported config extension: ${cliConfig}. ` +
+          'Use a .ts, .js, .mts, or .mjs file.',
+      )
+    }
+    if (!fs.existsSync(configPath) || !fs.statSync(configPath).isFile()) {
+      throw new CliConfigError(`[vue-site] Config file not found: ${configPath}`)
+    }
+    return basename(configPath)
+  }
+
+  const foundConfig = configCandidates.find((f) =>
+    fs.existsSync(resolve(cwd, f)),
+  )
+  if (foundConfig) return foundConfig
+
+  throw new CliConfigError(
     '\x1b[31mError: No site.config.ts found in the current directory.\x1b[0m\n\n' +
-    'Create a site.config.ts file:\n\n' +
-    '  import type { SiteConfig } from \'@bndynet/vue-site\'\n\n' +
-    '  export default {\n' +
-    '    title: \'My Site\',\n' +
-    '    nav: [\n' +
-    '      { label: \'Home\', icon: \'home\', page: () => import(\'./README.md?raw\') },\n' +
-    '    ],\n' +
-    '  } satisfies SiteConfig\n'
+      'Run `npx vue-site init` to create starter files, or create site.config.ts manually:\n\n' +
+      '  import type { SiteConfig } from \'@bndynet/vue-site\'\n\n' +
+      '  export default {\n' +
+      '    title: \'My Site\',\n' +
+      '    nav: [\n' +
+      '      { label: \'Home\', icon: \'home\', page: () => import(\'./README.md?raw\') },\n' +
+      '    ],\n' +
+      '  } satisfies SiteConfig\n',
   )
-  process.exit(1)
 }
 
 const VIRTUAL_ENTRY = 'virtual:vue-site-entry'
@@ -317,10 +431,10 @@ function buildBootstrapScript({ siteConfig, siteConfigSpecifier }) {
   ].join('\n')
 }
 
-function buildEntryCode(siteConfig) {
+function buildEntryCode(siteConfig, configFile) {
   return buildBootstrapScript({
     siteConfig,
-    siteConfigSpecifier: `/${foundConfig}`,
+    siteConfigSpecifier: `/${configFile}`,
   })
 }
 
@@ -358,8 +472,8 @@ function preloadAssetStubPlugin() {
   }
 }
 
-async function loadSiteConfig() {
-  const configPath = resolve(cwd, foundConfig)
+async function loadSiteConfig(configFile) {
+  const configPath = resolve(cwd, configFile)
   const raw = fs.readFileSync(configPath, 'utf-8')
 
   // Stub the framework's value imports so the config evaluates without the real (browser-only)
@@ -398,7 +512,7 @@ async function loadSiteConfig() {
       stubbed.replace(/import\.meta\.glob/g, '__vueSiteGlobStub')
   }
 
-  const isTs = /\.m?ts$/.test(foundConfig)
+  const isTs = /\.m?ts$/.test(configFile)
   // Write the stubbed entry next to the original so its relative imports (`./locales`) resolve.
   const entryFile = resolve(
     dirname(configPath),
@@ -428,7 +542,7 @@ async function loadSiteConfig() {
     return mod.default || {}
   } catch (e) {
     throw new Error(
-      `[vue-site] Could not pre-load site config from ${foundConfig}: ${e.message}\n` +
+      `[vue-site] Could not pre-load site config from ${configFile}: ${e.message}\n` +
         `  This usually means your config imports modules Node can't resolve directly ` +
         `(path aliases like @/..., or framework APIs other than defineConfig).`,
     )
@@ -704,8 +818,8 @@ function vueSitePlugin(entryCode, htmlTemplate, iconRegistryCode) {
 }
 
 async function buildViteConfig(options = {}) {
-  const { cliBase, siteConfig: siteConfigOption } = options
-  const siteConfig = siteConfigOption ?? (await loadSiteConfig())
+  const { cliBase, configFile, siteConfig: siteConfigOption } = options
+  const siteConfig = siteConfigOption ?? (await loadSiteConfig(configFile))
   const env = siteConfig.env || {}
   const {
     port,
@@ -816,7 +930,7 @@ async function buildViteConfig(options = {}) {
     }
   }
 
-  const entryCode = buildEntryCode(siteConfig)
+  const entryCode = buildEntryCode(siteConfig, configFile)
   const iconRegistryCode = buildIconRegistryCode(siteConfig)
   const htmlTemplate = buildHtmlShell(
     `<script type="module" src="/@id/__x00__${VIRTUAL_ENTRY}"></script>`,
@@ -953,9 +1067,15 @@ async function buildViteConfig(options = {}) {
 }
 
 async function run() {
-  const { command, cliBase } = parseCliArgv()
-  const siteConfig = await loadSiteConfig()
-  const viteConfig = await buildViteConfig({ cliBase, siteConfig })
+  const { command, cliBase, cliConfig } = parseCliArgv()
+  if (command === 'init') {
+    initSite()
+    return
+  }
+
+  const configFile = resolveSiteConfig(cliConfig)
+  const siteConfig = await loadSiteConfig(configFile)
+  const viteConfig = await buildViteConfig({ cliBase, configFile, siteConfig })
 
   if (command === 'dev') {
     const server = await createServer(viteConfig)
@@ -969,7 +1089,7 @@ async function run() {
     if (!hadHtml) {
       const bootstrapScript = buildBootstrapScript({
         siteConfig,
-        siteConfigSpecifier: `./${foundConfig}`,
+        siteConfigSpecifier: `./${configFile}`,
       })
       const buildHtml = buildHtmlShell(
         `<script type="module">\n${bootstrapScript}\n  </script>`,
@@ -992,14 +1112,16 @@ async function run() {
     server.printUrls()
   } else {
     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/',
+      'Usage: vue-site|vs <init|dev|build|preview> [--base=<path>] [--config=<file>]\n' +
+        '  init           Create site.config.ts, env.d.ts, and README.md without overwriting files\n' +
+        '  --base         Public path for assets (overrides env.vite.base); e.g. --base=/app/\n' +
+        '  --config, -c   Site config file in the current site root; e.g. site.config.prod.ts',
     )
     process.exit(1)
   }
 }
 
 run().catch((err) => {
-  console.error(err)
+  console.error(err instanceof CliConfigError ? err.message : err)
   process.exit(1)
 })

package/dist/auth.d.ts

@@ -3,11 +3,11 @@ import { AuthConfig, ResolvedNavItem } from './types';
 /** Query param carrying the originally requested path when redirecting to the login page. */
 export declare const AUTH_REDIRECT_QUERY = "redirect";
 /**
- * Startup-once pass that drops nav items the current user is not authorized to see, so they do not
- * appear in the rendered menu. Mirrors the pruning of `filterNavItems`: a hidden parent removes its
- * subtree, and a group left with no children and no own `page` / `link` is pruned. Routes are not
- * affected (they are still registered by `createSiteRouter`); only the menu list is filtered. An
- * item is shown only when `authorize` returns exactly `true`.
+ * Drop nav items the current user is not authorized to see, so they do not appear in the rendered
+ * menu. Mirrors the pruning of `filterNavItems`: a hidden parent removes its subtree, and a group
+ * left with no children and no own `page` / `link` is pruned. Routes are not affected (they are
+ * still registered by `createSiteRouter`); only the menu list is filtered. An item is shown only
+ * when `authorize` returns exactly `true`.
  */
 export declare function pruneNavByAuth(items: ResolvedNavItem[], auth: AuthConfig): Promise<ResolvedNavItem[]>;
 /**

package/dist/composables/useSiteConfig.d.ts

@@ -1,8 +1,12 @@
 import { InjectionKey } from 'vue';
 import { SiteConfig, ResolvedNavItem } from '../types';
 export interface SiteContext {
+    /** Original site configuration passed to `createSiteApp()`. */
     config: SiteConfig;
+    /** Auth-filtered nav tree rendered by the layout. Kept as a reactive array. */
     resolvedNav: ResolvedNavItem[];
+    /** Re-run auth menu filtering after consumer auth state changes, such as login/logout. */
+    refreshAuthNav: () => Promise<void>;
 }
 /** Use `Symbol.for` so pages still inject context if Vite resolves the package twice. */
 export declare const siteContextKey: InjectionKey<SiteContext>;

package/dist/create-app.d.ts

@@ -1,2 +1,11 @@
 import { SiteConfig } from './types';
+/**
+ * Returns the site config passed to `createSiteApp()`. Can be called from anywhere — plain
+ * modules, `bootstrap.ts` (after the app is created), utility functions, etc. — without a Vue
+ * injection context. Returns `undefined` if `createSiteApp` has not been called yet.
+ *
+ * For reactive, component-scoped access to the full `SiteContext` (config + nav + refreshAuthNav),
+ * use {@link useSiteConfig} inside a Vue component instead.
+ */
+export declare function getSiteConfig(): SiteConfig | undefined;
 export declare function createSiteApp(config: SiteConfig): Promise<import('vue').App<Element>>;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { SiteConfig } from './types';
-export { createSiteApp } from './create-app';
+export { createSiteApp, getSiteConfig } from './create-app';
 export { useTheme, themeRefKey } from './composables/useTheme';
 export { useLocale, localeRefKey } from './composables/useLocale';
 export { useLocalize } from './composables/useLocalize';
@@ -9,5 +9,23 @@ export { builtinMessages } from './i18n-messages';
 export { useSiteConfig } from './composables/useSiteConfig';
 export { builtinThemePalettes } from './theme/presets';
 export { ElMessage, ElMessageBox, ElNotification, } from 'element-plus';
-export type { SiteConfig, SiteEnvConfig, SiteViteConfig, SiteExternalLink, ShellConfig, ShellAction, ShellActionLoader, NavItem, StandalonePage, PageLayout, AuthRule, AuthContext, AuthConfig, RouterConfig, ThemeConfig, ThemeOption, ThemePaletteVars, ResolvedNavItem, LocaleCode, LocalizedString, IconRegistry, MessageRef, MessageTree, LocaleOption, I18nConfig, PageLoader, } from './types';
+export type { SiteConfig, SiteEnvConfig, SiteViteConfig, SiteCustomConfig, SiteExternalLink, ShellConfig, ShellAction, ShellActionLoader, NavItem, StandalonePage, PageLayout, AuthRule, AuthContext, AuthConfig, RouterConfig, ThemeConfig, ThemeOption, ThemePaletteVars, ResolvedNavItem, LocaleCode, LocalizedString, IconRegistry, MessageRef, MessageTree, LocaleOption, I18nConfig, PageLoader, } from './types';
+/**
+ * Type-safe identity for a single config object. Use the single-argument form for a standalone
+ * config file.
+ *
+ * When composing multiple config files (e.g. `site.config.prod.ts` importing a shared
+ * `site.config.common.ts`), use the two-argument form so `custom` is deep-merged: properties
+ * from the base `custom` are preserved unless explicitly overridden.
+ *
+ * @example
+ * // site.config.common.ts
+ * export default defineConfig({ custom: { apiBaseUrl: '/api', appName: 'MyApp' }, ... })
+ *
+ * // site.config.prod.ts
+ * import common from './site.config.common'
+ * export default defineConfig(common, { custom: { apiBaseUrl: 'https://prod.example.com/api' } })
+ * // Result: custom.apiBaseUrl is overridden, custom.appName is preserved.
+ */
 export declare function defineConfig(config: SiteConfig): SiteConfig;
+export declare function defineConfig(base: SiteConfig, overrides: Partial<SiteConfig>): SiteConfig;