@jasonshimmy/vite-plugin-cer-app 0.7.0 → 0.9.0

package/src/plugin/index.ts

@@ -94,6 +94,7 @@ export function resolveConfig(userConfig: CerAppConfig, root: string = process.c
     },
     runtimeConfig: {
       public: userConfig.runtimeConfig?.public ?? {},
+      private: userConfig.runtimeConfig?.private ?? {},
     },
   }
 }
@@ -104,6 +105,7 @@ export function resolveConfig(userConfig: CerAppConfig, root: string = process.c
 async function generateVirtualModule(
   id: string,
   config: ResolvedCerConfig,
+  ssr = false,
 ): Promise<string | null> {
   switch (id) {
     case RESOLVED_IDS.routes:
@@ -123,7 +125,7 @@ async function generateVirtualModule(
     case RESOLVED_IDS.serverMiddleware:
       return generateServerMiddlewareCode(config.serverMiddlewareDir)
     case RESOLVED_IDS.appConfig:
-      return generateAppConfigModule(config)
+      return generateAppConfigModule(config, ssr)
     case RESOLVED_IDS.loading:
       return generateLoadingCode(config.srcDir)
     case RESOLVED_IDS.error:
@@ -135,21 +137,29 @@ async function generateVirtualModule(
 
 /**
  * Generates a virtual module that exports the resolved app config.
+ * When `ssr` is true, also exports `_runtimePrivateDefaults` (server-only).
+ * The client bundle never receives private keys.
  */
-function generateAppConfigModule(config: ResolvedCerConfig): string {
+function generateAppConfigModule(config: ResolvedCerConfig, ssr = false): string {
   const exportedConfig = {
     mode: config.mode,
     router: config.router,
     ssg: config.ssg,
   }
   const publicConfig = config.runtimeConfig.public
-  return (
+  let code =
     `// AUTO-GENERATED by @jasonshimmy/vite-plugin-cer-app\n` +
     `export const appConfig = ${JSON.stringify(exportedConfig, null, 2)}\n` +
     `export default appConfig\n` +
     `\n` +
     `export const runtimeConfig = { public: ${JSON.stringify(publicConfig, null, 2)} }\n`
-  )
+
+  if (ssr) {
+    const privateDefaults = config.runtimeConfig.private
+    code += `\nexport const _runtimePrivateDefaults = ${JSON.stringify(privateDefaults, null, 2)}\n`
+  }
+
+  return code
 }
 
 /**
@@ -245,21 +255,26 @@ export function cerApp(userConfig: CerAppConfig = {}): Plugin[] {
       }
     },
 
-    async load(id: string) {
+    async load(id: string, options?: { ssr?: boolean }) {
       if (id === RESOLVED_APP_ENTRY) return APP_ENTRY_TEMPLATE
 
       const allResolved = Object.values(RESOLVED_IDS) as string[]
       if (!allResolved.includes(id)) return null
 
+      const ssr = options?.ssr ?? false
+      // For virtual:cer-app-config the SSR and client variants differ (private
+      // defaults are only included in the SSR bundle), so use separate cache keys.
+      const cacheKey = id === RESOLVED_IDS.appConfig ? `${id}:${ssr ? 'ssr' : 'client'}` : id
+
       // Return from cache if available
-      if (moduleCache.has(id)) {
-        return moduleCache.get(id)!
+      if (moduleCache.has(cacheKey)) {
+        return moduleCache.get(cacheKey)!
       }
 
       // Generate and cache
-      const code = await generateVirtualModule(id, config)
+      const code = await generateVirtualModule(id, config, ssr)
       if (code !== null) {
-        moduleCache.set(id, code)
+        moduleCache.set(cacheKey, code)
         return code
       }
 
@@ -364,11 +379,17 @@ export function cerApp(userConfig: CerAppConfig = {}): Plugin[] {
       composableExports = await scanComposableExports(config.composablesDir)
       await writeAutoImportDts(config.root, config.composablesDir, composableExports)
       writeTsconfigPaths(config.root, config.srcDir)
-      // Warm the virtual module cache
+      // Warm the virtual module cache.
+      // virtual:cer-app-config is cached under separate :client/:ssr keys (SSR
+      // build omits _runtimePrivateDefaults from the client variant), so use the
+      // correct key suffix here so load() hits the cache instead of regenerating.
       for (const resolvedId of Object.values(RESOLVED_IDS)) {
         const code = await generateVirtualModule(resolvedId, config)
         if (code !== null) {
-          moduleCache.set(resolvedId, code)
+          const cacheKey = resolvedId === RESOLVED_IDS.appConfig
+            ? `${resolvedId}:client`
+            : resolvedId
+          moduleCache.set(cacheKey, code)
         }
       }
     },

package/src/plugin/transforms/auto-import.ts

@@ -11,9 +11,9 @@ const RUNTIME_IMPORTS = `import { component, html, css, ref, computed, watch, wa
 
 const DIRECTIVE_IMPORTS = `import { when, each, match, anchorBlock } from '@jasonshimmy/custom-elements-runtime/directives';`
 
-const FRAMEWORK_IMPORTS = `import { useHead, usePageData, useInject, useRuntimeConfig } from '@jasonshimmy/vite-plugin-cer-app/composables';`
+const FRAMEWORK_IMPORTS = `import { useHead, usePageData, useInject, useRuntimeConfig, defineMiddleware, useSeoMeta, useCookie } from '@jasonshimmy/vite-plugin-cer-app/composables';`
 
-const FRAMEWORK_IDENTIFIERS = ['useHead', 'usePageData', 'useInject', 'useRuntimeConfig']
+const FRAMEWORK_IDENTIFIERS = ['useHead', 'usePageData', 'useInject', 'useRuntimeConfig', 'defineMiddleware', 'useSeoMeta', 'useCookie']
 
 const RUNTIME_IDENTIFIERS = [
   'component',
@@ -63,12 +63,13 @@ export function autoImportTransform(
   const normalizedId = normalize(id)
   const srcDir = normalize(opts.srcDir)
 
-  // Transform files inside app/pages/, app/layouts/, app/components/,
+  // Transform files inside app/pages/, app/layouts/, app/components/, app/middleware/
   // AND special convention files directly in app/ (loading.ts, error.ts, etc.)
   const isSubDir =
     normalizedId.startsWith(srcDir + '/pages/') ||
     normalizedId.startsWith(srcDir + '/layouts/') ||
-    normalizedId.startsWith(srcDir + '/components/')
+    normalizedId.startsWith(srcDir + '/components/') ||
+    normalizedId.startsWith(srcDir + '/middleware/')
   // Files directly in srcDir root (e.g. app/loading.ts, app/error.ts)
   const isRootConventionFile =
     normalizedId.startsWith(srcDir + '/') &&

package/src/plugin/virtual/routes.ts

@@ -256,7 +256,13 @@ export async function generateRoutesCode(pagesDir: string): Promise<string> {
       `      for (const name of ${mwLiteral}) {\n` +
       `        const handler = middleware[name]\n` +
       `        if (typeof handler !== 'function') continue\n` +
-      `        const result = await new Promise((resolve) => handler(to, from, resolve))\n` +
+      `        let result\n` +
+      `        try {\n` +
+      `          result = await handler(to, from)\n` +
+      `        } catch (err) {\n` +
+      `          console.error('[cer-app] Middleware "' + name + '" threw an error:', err)\n` +
+      `          return false\n` +
+      `        }\n` +
       `        if (typeof result === 'string') return result\n` +
       `        if (result === false) return false\n` +
       `      }\n` +

package/src/runtime/composables/define-middleware.ts

@@ -0,0 +1,17 @@
+import type { MiddlewareFn } from '../../types/middleware.js'
+
+/**
+ * Identity helper that gives TypeScript the correct `MiddlewareFn` type
+ * without any runtime cost.
+ *
+ * @example
+ * // app/middleware/auth.ts
+ * export default defineMiddleware(async (to, from) => {
+ *   const isLoggedIn = checkSession()
+ *   if (!isLoggedIn) return '/login'   // redirect
+ *   return true                         // allow
+ * })
+ */
+export function defineMiddleware(fn: MiddlewareFn): MiddlewareFn {
+  return fn
+}

package/src/runtime/composables/index.ts

@@ -2,4 +2,10 @@ export { useHead, beginHeadCollection, endHeadCollection, serializeHeadTags } fr
 export type { HeadInput } from './use-head.js'
 export { usePageData } from './use-page-data.js'
 export { useInject } from './use-inject.js'
-export { useRuntimeConfig, initRuntimeConfig } from './use-runtime-config.js'
+export { useRuntimeConfig, initRuntimeConfig, resolvePrivateConfig } from './use-runtime-config.js'
+export type { RuntimeConfigResult, RuntimeConfigPublic, RuntimeConfigPrivate } from './use-runtime-config.js'
+export { defineMiddleware } from './define-middleware.js'
+export { useSeoMeta } from './use-seo-meta.js'
+export type { SeoMetaInput } from './use-seo-meta.js'
+export { useCookie } from './use-cookie.js'
+export type { CookieOptions, CookieRef } from './use-cookie.js'

package/src/runtime/composables/use-cookie.ts

@@ -0,0 +1,128 @@
+import type { IncomingMessage, ServerResponse } from 'node:http'
+
+export interface CookieOptions {
+  /** Cookie path. Defaults to '/' when setting/removing. */
+  path?: string
+  domain?: string
+  /** Max age in seconds. */
+  maxAge?: number
+  expires?: Date
+  httpOnly?: boolean
+  secure?: boolean
+  sameSite?: 'Strict' | 'Lax' | 'None'
+}
+
+export interface CookieRef {
+  /** The current cookie value, or undefined if not set. */
+  readonly value: string | undefined
+  /** Write the cookie value. */
+  set(value: string, options?: CookieOptions): void
+  /** Remove the cookie by setting Max-Age=0. */
+  remove(options?: CookieOptions): void
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function parseCookies(cookieHeader: string): Record<string, string> {
+  const result: Record<string, string> = {}
+  for (const part of cookieHeader.split(';')) {
+    const eqIdx = part.indexOf('=')
+    if (eqIdx < 0) continue
+    const key = part.slice(0, eqIdx).trim()
+    const rawValue = part.slice(eqIdx + 1).trim()
+    try {
+      result[key] = decodeURIComponent(rawValue)
+    } catch {
+      result[key] = rawValue
+    }
+  }
+  return result
+}
+
+function serializeCookie(name: string, value: string, options: CookieOptions = {}): string {
+  let str = `${encodeURIComponent(name)}=${encodeURIComponent(value)}`
+  const path = options.path ?? '/'
+  if (path) str += `; Path=${path}`
+  if (options.domain) str += `; Domain=${options.domain}`
+  if (options.maxAge !== undefined) str += `; Max-Age=${options.maxAge}`
+  if (options.expires) str += `; Expires=${options.expires.toUTCString()}`
+  if (options.httpOnly) str += '; HttpOnly'
+  if (options.secure) str += '; Secure'
+  if (options.sameSite) str += `; SameSite=${options.sameSite}`
+  return str
+}
+
+function appendSetCookie(res: ServerResponse, cookie: string): void {
+  const existing = res.getHeader('Set-Cookie')
+  const list: string[] = existing == null
+    ? []
+    : Array.isArray(existing) ? existing : [String(existing)]
+  list.push(cookie)
+  res.setHeader('Set-Cookie', list)
+}
+
+// ─── Composable ───────────────────────────────────────────────────────────────
+
+/**
+ * Isomorphic cookie composable.
+ *
+ * - **Server (SSR/SSG)**: reads from `req.headers.cookie` via AsyncLocalStorage;
+ *   writes/removes via `res.setHeader('Set-Cookie', ...)`.
+ * - **Client**: reads and writes `document.cookie`.
+ *
+ * It is auto-imported, so you don't need to import it manually.
+ *
+ * @example
+ * ```ts
+ * const token = useCookie('auth-token')
+ * console.log(token.value)           // read
+ * token.set('abc123')                // write
+ * token.remove()                     // delete
+ * ```
+ */
+export function useCookie(name: string, defaultOptions: CookieOptions = {}): CookieRef {
+  const g = globalThis as Record<string, unknown>
+
+  // ── SSR path ──────────────────────────────────────────────────────────────
+  const store = g['__CER_REQ_STORE__'] as
+    | { getStore(): { req: IncomingMessage; res: ServerResponse } | null }
+    | undefined
+
+  if (store) {
+    const ctx = store.getStore()
+    if (ctx) {
+      const { req, res } = ctx
+      const parsed = parseCookies(req.headers['cookie'] ?? '')
+      return {
+        value: parsed[name],
+        set(value: string, options?: CookieOptions) {
+          appendSetCookie(res, serializeCookie(name, value, { ...defaultOptions, ...options }))
+        },
+        remove(options?: CookieOptions) {
+          appendSetCookie(res, serializeCookie(name, '', { ...defaultOptions, ...options, maxAge: 0 }))
+        },
+      }
+    }
+  }
+
+  // ── Client path ───────────────────────────────────────────────────────────
+  if (typeof document !== 'undefined') {
+    const parsed = parseCookies(document.cookie)
+    return {
+      value: parsed[name],
+      set(value: string, options?: CookieOptions) {
+        document.cookie = serializeCookie(name, value, { ...defaultOptions, ...options })
+      },
+      remove(options?: CookieOptions) {
+        document.cookie = serializeCookie(name, '', { ...defaultOptions, ...options, maxAge: 0 })
+      },
+    }
+  }
+
+  // ── Build-time / unknown context ──────────────────────────────────────────
+  return {
+    value: undefined,
+    set() {},
+    remove() {},
+  }
+}

package/src/runtime/composables/use-runtime-config.ts

@@ -1,29 +1,42 @@
+export interface RuntimeConfigPublic {
+  [key: string]: unknown
+}
+
+export interface RuntimeConfigPrivate {
+  [key: string]: string
+}
+
+export interface RuntimeConfigResult {
+  public: RuntimeConfigPublic
+  private?: RuntimeConfigPrivate
+}
+
 /**
- * Returns the public runtime configuration set in `cer.config.ts` under
- * `runtimeConfig.public`. Available on both server and client.
+ * Returns the runtime configuration set in `cer.config.ts`.
  *
- * Values are baked in at build time from `virtual:cer-app-config`, so only
- * static/env-var values should be placed here. For truly dynamic config,
- * use a loader or API route.
+ * - `public` — available on both server and client.
+ * - `private` — available on the server only (resolved from `process.env` at
+ *   startup). Never present on the client.
  *
  * @example
  * // cer.config.ts
  * export default defineConfig({
  *   runtimeConfig: {
  *     public: { apiBase: process.env.VITE_API_BASE ?? '/api' },
+ *     private: { dbUrl: '', secretKey: '' },
  *   },
  * })
  *
- * // app/pages/index.ts
- * const config = useRuntimeConfig()
- * fetch(config.public.apiBase + '/posts')
+ * // app/pages/index.ts (loader — server-only)
+ * const { private: priv } = useRuntimeConfig()
+ * const rows = await db.query(priv.dbUrl)
  */
-export function useRuntimeConfig(): { public: Record<string, unknown> } {
+export function useRuntimeConfig(): RuntimeConfigResult {
   // Dynamic import resolved at runtime — avoids a static circular dependency
   // between the composable and the virtual module.
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const mod = (globalThis as any).__cerRuntimeConfig
-  if (mod) return mod as { public: Record<string, unknown> }
+  if (mod) return mod as RuntimeConfigResult
 
   // Fallback: empty config (e.g. in test environments without the virtual module).
   return { public: {} }
@@ -34,7 +47,50 @@ export function useRuntimeConfig(): { public: Record<string, unknown> } {
  * globalThis so useRuntimeConfig() can access it synchronously in any context
  * (component render, composable, server handler).
  */
-export function initRuntimeConfig(config: { public: Record<string, unknown> }): void {
+export function initRuntimeConfig(config: RuntimeConfigResult): void {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   ;(globalThis as any).__cerRuntimeConfig = config
 }
+
+/**
+ * Converts a camelCase or mixed key to UPPER_SNAKE_CASE for env var lookup.
+ * Examples: `dbUrl` → `DB_URL`, `secretKey` → `SECRET_KEY`, `API_KEY` → `API_KEY`.
+ */
+function toUpperSnakeCase(key: string): string {
+  return key
+    .replace(/([a-z])([A-Z])/g, '$1_$2')
+    .toUpperCase()
+}
+
+/**
+ * Resolves a private config object by looking up each key in the supplied
+ * environment variable map, with the following precedence:
+ *
+ * 1. `env[key]`                   — exact case (e.g. `process.env.dbUrl`)
+ * 2. `env[UPPER_SNAKE_CASE(key)]` — conventional env var form (e.g. `process.env.DB_URL`)
+ * 3. `defaultValue`               — the declared default from `cer.config.ts`
+ *
+ * Accepts an optional `env` parameter so the function is unit-testable
+ * without mutating `process.env`.
+ */
+export function resolvePrivateConfig(
+  defaults: Record<string, string>,
+  env: Record<string, string | undefined> = process.env as Record<string, string | undefined>,
+): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(defaults).map(([key, defaultValue]) => {
+      const envKey = toUpperSnakeCase(key)
+      const resolved = env[key] ?? env[envKey] ?? defaultValue
+      // Warn when no env var was found and the declared default is an empty string.
+      // An empty-string default is the conventional way to declare a required secret
+      // (the key exists for typing purposes but has no safe default value).
+      if (resolved === '' && env[key] === undefined && env[envKey] === undefined) {
+        console.warn(
+          `[cer-app] runtimeConfig.private: "${key}" is an empty string — ` +
+          `set ${envKey} in the environment to provide a value.`,
+        )
+      }
+      return [key, resolved]
+    }),
+  )
+}

package/src/runtime/composables/use-seo-meta.ts

@@ -0,0 +1,75 @@
+import { useHead } from './use-head.js'
+
+export interface SeoMetaInput {
+  /** Sets the document title. */
+  title?: string
+  /** Sets the meta description. */
+  description?: string
+  // Open Graph
+  ogTitle?: string
+  ogDescription?: string
+  ogImage?: string
+  ogUrl?: string
+  /** e.g. `'website'`, `'article'`. No tag is emitted when omitted. */
+  ogType?: string
+  ogSiteName?: string
+  // Twitter / X
+  /** e.g. `'summary'`, `'summary_large_image'`. No tag is emitted when omitted. */
+  twitterCard?: string
+  twitterTitle?: string
+  twitterDescription?: string
+  twitterImage?: string
+  /** Twitter/X site handle, e.g. '@mysite'. */
+  twitterSite?: string
+  /** Canonical URL injected as <link rel="canonical">. */
+  canonical?: string
+}
+
+/**
+ * Thin wrapper over `useHead()` for common SEO tags.
+ *
+ * Sets the page title, meta description, Open Graph tags, Twitter Card tags,
+ * and a canonical link element. Only tags with a non-undefined value are emitted.
+ *
+ * It is auto-imported, so you don't need to import it manually.
+ *
+ * @example
+ * ```ts
+ * useSeoMeta({
+ *   title: 'My page',
+ *   description: 'A great page.',
+ *   ogImage: 'https://example.com/og.png',
+ *   canonical: 'https://example.com/my-page',
+ * })
+ * ```
+ */
+export function useSeoMeta(input: SeoMetaInput): void {
+  const meta: Array<Record<string, string>> = []
+  const link: Array<Record<string, string>> = []
+
+  if (input.description !== undefined) meta.push({ name: 'description', content: input.description })
+
+  // Open Graph
+  if (input.ogTitle !== undefined) meta.push({ property: 'og:title', content: input.ogTitle })
+  if (input.ogDescription !== undefined) meta.push({ property: 'og:description', content: input.ogDescription })
+  if (input.ogImage !== undefined) meta.push({ property: 'og:image', content: input.ogImage })
+  if (input.ogUrl !== undefined) meta.push({ property: 'og:url', content: input.ogUrl })
+  if (input.ogType !== undefined) meta.push({ property: 'og:type', content: input.ogType })
+  if (input.ogSiteName !== undefined) meta.push({ property: 'og:site_name', content: input.ogSiteName })
+
+  // Twitter / X
+  if (input.twitterCard !== undefined) meta.push({ name: 'twitter:card', content: input.twitterCard })
+  if (input.twitterTitle !== undefined) meta.push({ name: 'twitter:title', content: input.twitterTitle })
+  if (input.twitterDescription !== undefined) meta.push({ name: 'twitter:description', content: input.twitterDescription })
+  if (input.twitterImage !== undefined) meta.push({ name: 'twitter:image', content: input.twitterImage })
+  if (input.twitterSite !== undefined) meta.push({ name: 'twitter:site', content: input.twitterSite })
+
+  // Canonical link
+  if (input.canonical !== undefined) link.push({ rel: 'canonical', href: input.canonical })
+
+  useHead({
+    title: input.title,
+    meta: meta.length > 0 ? meta : undefined,
+    link: link.length > 0 ? link : undefined,
+  })
+}

package/src/runtime/entry-server-template.ts

@@ -21,17 +21,21 @@ import routes from 'virtual:cer-routes'
 import layouts from 'virtual:cer-layouts'
 import plugins from 'virtual:cer-plugins'
 import apiRoutes from 'virtual:cer-server-api'
-import { runtimeConfig } from 'virtual:cer-app-config'
+import { runtimeConfig, _runtimePrivateDefaults } from 'virtual:cer-app-config'
 import { registerBuiltinComponents } from '@jasonshimmy/custom-elements-runtime'
 import { registerEntityMap, renderToStreamWithJITCSSDSD, DSD_POLYFILL_SCRIPT } from '@jasonshimmy/custom-elements-runtime/ssr'
 import entitiesJson from '@jasonshimmy/custom-elements-runtime/entities.json'
 import { initRouter } from '@jasonshimmy/custom-elements-runtime/router'
-import { beginHeadCollection, endHeadCollection, serializeHeadTags, initRuntimeConfig } from '@jasonshimmy/vite-plugin-cer-app/composables'
+import { beginHeadCollection, endHeadCollection, serializeHeadTags, initRuntimeConfig, resolvePrivateConfig } from '@jasonshimmy/vite-plugin-cer-app/composables'
 import { errorTag } from 'virtual:cer-error'
 import { createIsrHandler } from '@jasonshimmy/vite-plugin-cer-app/isr'
 
 registerBuiltinComponents()
-initRuntimeConfig(runtimeConfig)
+
+// Resolve private config from environment variables at server startup.
+// Each key declared in runtimeConfig.private is looked up in process.env,
+// first as-is, then as ALL_CAPS. The declared default is used as fallback.
+initRuntimeConfig({ ...runtimeConfig, private: resolvePrivateConfig(_runtimePrivateDefaults ?? {}) })
 
 // Pre-load the full HTML entity map so named entities like — decode
 // correctly during SSR. Without this the bundled runtime falls back to a
@@ -64,6 +68,12 @@ const _cerDataStore = new AsyncLocalStorage()
 // Expose the store so the usePageData() composable can read it server-side.
 ;(globalThis).__CER_DATA_STORE__ = _cerDataStore
 
+// Async-local storage for request-scoped req/res access.
+// Allows isomorphic composables (e.g. useCookie) to read/write HTTP headers
+// without prop-drilling the request context through the component tree.
+const _cerReqStore = new AsyncLocalStorage()
+;(globalThis).__CER_REQ_STORE__ = _cerReqStore
+
 // Load the Vite-built client index.html (dist/client/index.html) so every SSR
 // response includes the client-side scripts needed for hydration and routing.
 // The server bundle lives at dist/server/server.js, so ../client resolves correctly.
@@ -188,6 +198,7 @@ const _prepareRequest = async (req) => {
 }
 
 export const handler = async (req, res) => {
+  await _cerReqStore.run({ req, res }, async () => {
   await _cerDataStore.run(null, async () => {
     const { vnode, router, head, status } = await _prepareRequest(req)
     if (status != null) res.statusCode = status
@@ -247,6 +258,7 @@ export const handler = async (req, res) => {
     // Inject DSD polyfill immediately before </body>, then close the document.
     res.end(DSD_POLYFILL_SCRIPT + fromBodyClose)
   })
+  })
 }
 
 // ISR-wrapped handler for production integrations (Express, Hono, Fastify).

package/src/types/config.ts

@@ -22,6 +22,10 @@ export interface RuntimePublicConfig {
   [key: string]: unknown
 }
 
+export interface RuntimePrivateConfig {
+  [key: string]: string
+}
+
 export interface RuntimeConfig {
   /**
    * Public runtime config — available on both server and client via
@@ -36,6 +40,17 @@ export interface RuntimeConfig {
    * }
    */
   public?: RuntimePublicConfig
+  /**
+   * Server-only secrets — never serialized into the client bundle.
+   * Declare keys with empty-string defaults here; at server startup each key
+   * is resolved from `process.env[KEY]` (case-insensitive, ALL_CAPS preferred).
+   *
+   * @example
+   * runtimeConfig: {
+   *   private: { dbUrl: '', secretKey: '' },
+   * }
+   */
+  private?: RuntimePrivateConfig
 }
 
 export interface CerAppConfig {

package/src/types/index.ts

@@ -1,6 +1,6 @@
-export type { CerAppConfig, SsgConfig, JitCssConfig, AutoImportsConfig, RuntimeConfig, RuntimePublicConfig } from './config.js'
+export type { CerAppConfig, SsgConfig, JitCssConfig, AutoImportsConfig, RuntimeConfig, RuntimePublicConfig, RuntimePrivateConfig } from './config.js'
 export { defineConfig } from './config.js'
 export type { HydrateStrategy, SsgPathsContext, PageSsgConfig, PageMeta, PageLoaderContext, PageLoader } from './page.js'
 export type { ApiRequest, ApiResponse, ApiHandler, ApiContext } from './api.js'
 export type { AppContext, AppPlugin } from './plugin.js'
-export type { NextFunction, RouteMiddleware, ServerMiddleware } from './middleware.js'
+export type { MiddlewareFn, GuardResult, ServerMiddleware } from './middleware.js'

package/src/types/middleware.ts

@@ -1,13 +1,15 @@
 import type { RouteState } from '@jasonshimmy/custom-elements-runtime/router'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 
-export type NextFunction = (redirectTo?: string) => void
+/**
+ * Return value from a route middleware function:
+ * - `true`   — allow navigation
+ * - `false`  — block navigation
+ * - `string` — redirect to that path
+ */
+export type GuardResult = boolean | string | Promise<boolean | string>
 
-export type RouteMiddleware = (
-  to: RouteState,
-  from: RouteState | null,
-  next: NextFunction,
-) => void | Promise<void>
+export type MiddlewareFn = (to: RouteState, from: RouteState | null) => GuardResult
 
 export type ServerMiddleware = (
   req: IncomingMessage,