@jasonshimmy/vite-plugin-cer-app 0.19.2 → 0.20.0

package/src/plugin/content/index.ts

@@ -0,0 +1,236 @@
+import { join } from 'pathe'
+import { existsSync } from 'node:fs'
+import type { Plugin, ViteDevServer, ResolvedConfig } from 'vite'
+import type { CerContentConfig } from '../../types/content.js'
+import type { ContentItem } from '../../types/content.js'
+import { scanContentFiles } from './scanner.js'
+import { parseContentFileAsync, toContentMeta } from './parser.js'
+import { emitContentFiles } from './emitter.js'
+import { buildSearchIndex } from './search.js'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+
+/** The globalThis key used to share the in-memory content store with ContentClient. */
+export const CONTENT_STORE_KEY = '__CER_CONTENT_STORE__'
+
+/**
+ * Resolves the absolute content directory from the framework config.
+ * `dir` is relative to the project root (not the app source directory),
+ * so `content/` sits alongside `app/`, `server/`, and `public/`.
+ */
+export function resolveContentDir(root: string, contentConfig?: CerContentConfig): string {
+  const dir = contentConfig?.dir ?? 'content'
+  return join(root, dir)
+}
+
+/**
+ * Loads all content files from `contentDir`, parses them concurrently, and
+ * returns the full `ContentItem[]`. Excludes drafts in production unless
+ * `drafts: true`. Uses async I/O + `Promise.all` for concurrent disk reads,
+ * which is significantly faster than sequential `readFileSync` at 10k+ pages.
+ */
+export async function loadContentStore(
+  contentDir: string,
+  isDraft: boolean,
+  isProduction: boolean,
+): Promise<ContentItem[]> {
+  if (!existsSync(contentDir)) return []
+
+  const files = await scanContentFiles(contentDir)
+
+  const results = await Promise.all(
+    files.map(async (file) => {
+      try {
+        const item = await parseContentFileAsync(file, contentDir)
+        // Skip drafts in production (unless drafts flag is set)
+        if (isProduction && !isDraft && item.draft === true) return null
+        return item
+      } catch (err) {
+        // Warn and skip unparseable / invalid files so one bad file does not
+        // abort the entire build.  Invalid JSON files produce a descriptive
+        // error from the parser; other errors are also surfaced here.
+        console.warn(
+          `[cer-app] Skipping content file (parse error): ${file.filePath}\n  ${(err as Error).message}`,
+        )
+        return null
+      }
+    }),
+  )
+
+  return results.filter((item): item is ContentItem => item !== null)
+}
+
+// ─── Dev server derived-data cache ───────────────────────────────────────────
+// Re-computing the manifest JSON and search index on every request is O(n) at
+// 10k+ pages. Cache them as serialised strings, keyed by the store array
+// reference. When refreshStore() replaces the store, the reference changes
+// and the cache is automatically invalidated on the next request.
+
+let _devCacheStoreRef: ContentItem[] | null = null
+let _devCacheManifestJson: string | null = null
+let _devCacheSearchIndexJson: string | null = null
+
+function invalidateDevCaches(): void {
+  _devCacheStoreRef = null
+  _devCacheManifestJson = null
+  _devCacheSearchIndexJson = null
+}
+
+function ensureDevCache(store: ContentItem[]): void {
+  if (_devCacheStoreRef === store) return
+  _devCacheStoreRef = store
+  _devCacheManifestJson = JSON.stringify(store.map(toContentMeta))
+  _devCacheSearchIndexJson = buildSearchIndex(store)
+}
+
+/**
+ * Registers the `/_content/*` dev middleware that serves content from the
+ * in-memory store populated by `buildStart`.
+ */
+function registerDevMiddleware(server: ViteDevServer, _contentDir: string): void {
+  server.middlewares.use(async (req: IncomingMessage, res: ServerResponse, next: () => void) => {
+    const url = (req as { url?: string }).url ?? ''
+    if (!url.startsWith('/_content/')) {
+      next()
+      return
+    }
+
+    const g = globalThis as Record<string, unknown>
+    const store = g[CONTENT_STORE_KEY] as ContentItem[] | undefined
+
+    if (!store) {
+      res.statusCode = 503
+      res.end('Content store not ready')
+      return
+    }
+
+    // Rebuild derived caches if the store reference has changed (post-HMR).
+    ensureDevCache(store)
+
+    const suffix = url.slice('/_content/'.length).split('?')[0]
+
+    if (suffix === 'manifest.json') {
+      res.setHeader('Content-Type', 'application/json')
+      res.setHeader('Cache-Control', 'no-store')
+      res.end(_devCacheManifestJson!)
+      return
+    }
+
+    if (suffix === 'search-index.json') {
+      res.setHeader('Content-Type', 'application/json')
+      res.setHeader('Cache-Control', 'no-store')
+      res.end(_devCacheSearchIndexJson!)
+      return
+    }
+
+    // Individual document: suffix is like "blog/hello.json" or "index.json"
+    if (suffix.endsWith('.json')) {
+      const rawPath = suffix.slice(0, -'.json'.length) // strip .json
+      // Reverse the contentPathToFile mapping:
+      // "index" → "/" and "blog/hello" → "/blog/hello"
+      const _path = rawPath === 'index' ? '/' : '/' + rawPath
+      const item = store.find((i) => i._path === _path)
+      if (item) {
+        res.setHeader('Content-Type', 'application/json')
+        res.setHeader('Cache-Control', 'no-store')
+        res.end(JSON.stringify(item))
+        return
+      }
+    }
+
+    res.statusCode = 404
+    res.end('Not found')
+  })
+}
+
+/**
+ * `cerContent()` — Vite sub-plugin that provides the file-based content layer.
+ *
+ * - `buildStart`: scans and parses the content directory, populates `globalThis.__CER_CONTENT_STORE__`
+ * - `configureServer`: registers `/_content/*` dev middleware from the same store; watches for HMR
+ * - `closeBundle`: emits `_content/*.json` into the Vite output directory for this build
+ *   (e.g. `dist/client/_content/` for SSR client, `dist/_content/` for SPA/SSG)
+ *
+ * The content directory is resolved relative to the **project root** (not the
+ * app source directory), so a default config produces `{root}/content/` — at
+ * the same level as `app/`, `server/`, and `public/`.
+ */
+export function cerContent(
+  contentConfig?: CerContentConfig,
+): Plugin {
+  const contentDirName = contentConfig?.dir ?? 'content'
+  const includeDrafts = contentConfig?.drafts ?? false
+  // Resolved in configResolved; empty until then.
+  let _resolvedContentDir = ''
+  let _resolvedOutDir = ''
+  let _isSsr = false
+
+  const plugin: Plugin = {
+    name: '@jasonshimmy/vite-plugin-cer-app:content',
+
+    configResolved(resolvedConfig: ResolvedConfig) {
+      // Content lives at {root}/{dir} — parallel to app/, server/, public/.'
+      _resolvedContentDir = join(resolvedConfig.root, contentDirName)
+      _resolvedOutDir = resolvedConfig.build.outDir
+      _isSsr = !!resolvedConfig.build.ssr
+    },
+
+    async buildStart() {
+      const isProduction = this.meta.watchMode === false
+      const items = await loadContentStore(_resolvedContentDir, includeDrafts, isProduction)
+      const g = globalThis as Record<string, unknown>
+      g[CONTENT_STORE_KEY] = items
+    },
+
+    configureServer(server: ViteDevServer) {
+      registerDevMiddleware(server, _resolvedContentDir)
+
+      // HMR: re-parse on content file changes
+      server.watcher.add(_resolvedContentDir)
+
+      server.watcher.on('add', async (file: string) => {
+        if (!file.startsWith(_resolvedContentDir)) return
+        await refreshStore(_resolvedContentDir, includeDrafts)
+        server.ws.send({ type: 'full-reload' })
+      })
+
+      server.watcher.on('change', async (file: string) => {
+        if (!file.startsWith(_resolvedContentDir)) return
+        await refreshStore(_resolvedContentDir, includeDrafts)
+        server.ws.send({ type: 'full-reload' })
+      })
+
+      server.watcher.on('unlink', async (file: string) => {
+        if (!file.startsWith(_resolvedContentDir)) return
+        await refreshStore(_resolvedContentDir, includeDrafts)
+        server.ws.send({ type: 'full-reload' })
+      })
+    },
+
+    closeBundle() {
+      // Only emit for the client/SPA/SSG build pass, not the SSR server bundle pass.
+      // This prevents double scanning, parsing, and writing at build time.
+      // The SSR runtime reads from dist/client/_content/ (or dist/_content/) at runtime.
+      if (_isSsr) return
+      const g = globalThis as Record<string, unknown>
+      // Use the populated store; fall back to [] so the client never receives a 404 on
+      // /_content/manifest.json even if buildStart failed to populate the store.
+      const store = (g[CONTENT_STORE_KEY] as ContentItem[] | undefined) ?? []
+
+      const searchIndex = buildSearchIndex(store)
+      emitContentFiles(store, _resolvedOutDir, searchIndex)
+    },
+  }
+
+  return plugin
+}
+
+async function refreshStore(contentDir: string, includeDrafts: boolean): Promise<void> {
+  // HMR runs in dev (watchMode=true) — use isProduction=false so draft items
+  // remain visible, matching the initial buildStart behaviour in dev mode.
+  const items = await loadContentStore(contentDir, includeDrafts, false)
+  const g = globalThis as Record<string, unknown>
+  g[CONTENT_STORE_KEY] = items
+  // Invalidate the dev middleware caches so the next request rebuilds manifest
+  // and search-index from the updated store.
+  invalidateDevCaches()
+}

package/src/plugin/content/parser.ts

@@ -0,0 +1,192 @@
+import matter from 'gray-matter'
+import { marked, type Token } from 'marked'
+import { readFileSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import type { ContentHeading, ContentItem, ContentMeta } from '../../types/content.js'
+import type { ContentFile } from './scanner.js'
+import { fileToContentPath } from './path-utils.js'
+import { relative } from 'pathe'
+
+// ─── Heading extraction ───────────────────────────────────────────────────────
+
+/** Slugify a plain-text heading string into a URL-safe id. */
+function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^\w\s-]/g, '')
+    .trim()
+    .replace(/[\s_]+/g, '-')
+    .replace(/-+/g, '-')
+}
+
+/**
+ * Walks a marked token list and collects heading tokens.
+ * Mutates heading tokens in place to add `id` attributes to the HTML output.
+ */
+function extractHeadings(tokens: Token[]): ContentHeading[] {
+  const headings: ContentHeading[] = []
+
+  const walk = (tokenList: Token[]) => {
+    for (const token of tokenList) {
+      if (token.type === 'heading') {
+        const text = token.text
+        const id = slugify(text)
+        headings.push({
+          depth: token.depth as ContentHeading['depth'],
+          id,
+          text,
+        })
+      }
+      // Walk nested tokens (e.g. list items, blockquote)
+      if ('tokens' in token && Array.isArray(token.tokens)) {
+        walk(token.tokens)
+      }
+    }
+  }
+
+  walk(tokens)
+  return headings
+}
+
+// ─── Custom renderer: add id to heading tags ─────────────────────────────────
+
+const renderer = new marked.Renderer()
+
+renderer.heading = function ({ tokens, depth }) {
+  const text = tokens.map((t) => ('text' in t ? (t.text as string) : '')).join('')
+  const id = slugify(text)
+  const level = depth as ContentHeading['depth']
+  const innerHtml = marked.parseInline(tokens.map((t) => ('raw' in t ? t.raw : '')).join(''))
+  return `<h${level} id="${id}">${innerHtml}</h${level}>\n`
+}
+
+// ─── Parser ───────────────────────────────────────────────────────────────────
+
+/**
+ * Core parse logic shared by both the sync and async variants.
+ * Accepts pre-read `raw` content so the caller controls I/O scheduling.
+ *
+ * Date normalization: gray-matter parses bare YAML dates (e.g. `date: 2026-04-03`)
+ * as JavaScript `Date` objects. This causes a type mismatch — the in-memory server
+ * store contains `Date` objects while the client, which reads via JSON.stringify/parse,
+ * always gets ISO strings. All `Date` values are normalised to `YYYY-MM-DD` strings
+ * here so both paths are consistent.
+ */
+function parseContentFileFromRaw(
+  file: ContentFile,
+  contentDir: string,
+  raw: string,
+): ContentItem {
+  const _path = fileToContentPath(file.filePath, contentDir)
+  const _file = relative(contentDir, file.filePath)
+
+  if (file.ext === 'json') {
+    // Validate JSON so users get a clear error at build time rather than a
+    // silently broken body string that only surfaces at render time.
+    try {
+      JSON.parse(raw)
+    } catch (err) {
+      throw new Error(
+        `Invalid JSON in content file "${file.filePath}": ${(err as Error).message}`,
+      )
+    }
+    return {
+      _path,
+      _file,
+      _type: 'json',
+      body: raw,
+      toc: [],
+    }
+  }
+
+  // ── Markdown ─────────────────────────────────────────────────────────────
+  const parsed = matter(raw)
+  const frontmatter = parsed.data as ContentMeta
+  const content = parsed.content
+
+  // Split on <!-- more --> for excerpt.
+  // The marker is stripped from bodySource so it does not appear as an HTML
+  // comment in the rendered body — spec says body is "all content minus the
+  // marker itself".
+  const MORE_MARKER = '<!-- more -->'
+  const moreIndex = content.indexOf(MORE_MARKER)
+  const hasMore = moreIndex !== -1
+  const bodySource = hasMore
+    ? content.slice(0, moreIndex) + content.slice(moreIndex + MORE_MARKER.length)
+    : content
+  const excerptSource = hasMore ? content.slice(0, moreIndex).trim() : null
+
+  // Tokenise once and extract headings
+  const lexer = new marked.Lexer()
+  const tokens = lexer.lex(bodySource)
+  const toc = extractHeadings(tokens)
+
+  // Render full body with custom renderer (adds id= to headings)
+  const body = marked.parser(tokens, { renderer }) as string
+
+  // Render excerpt if present
+  const excerpt = excerptSource !== null
+    ? (marked.parse(excerptSource, { renderer }) as string)
+    : undefined
+
+  const item: ContentItem = {
+    ...frontmatter,
+    _path,
+    _file,
+    _type: 'markdown',
+    body,
+    toc,
+  }
+
+  if (excerpt !== undefined) {
+    item.excerpt = excerpt
+  }
+
+  // Normalise any Date objects introduced by gray-matter's YAML parser to
+  // YYYY-MM-DD strings. Without this, the server in-memory store holds Date
+  // objects while the client (after JSON round-trip) holds strings, causing
+  // date comparisons in .where() predicates to silently misbehave server-side.
+  for (const key of Object.keys(item)) {
+    if ((item as Record<string, unknown>)[key] instanceof Date) {
+      ;(item as Record<string, unknown>)[key] = ((item as Record<string, unknown>)[key] as Date)
+        .toISOString()
+        .split('T')[0]
+    }
+  }
+
+  return item
+}
+
+/**
+ * Parses a single content file synchronously and returns a `ContentItem`.
+ * Prefer `parseContentFileAsync` in batch contexts (e.g. `loadContentStore`)
+ * to allow concurrent I/O.
+ */
+export function parseContentFile(
+  file: ContentFile,
+  contentDir: string,
+): ContentItem {
+  const raw = readFileSync(file.filePath, 'utf-8')
+  return parseContentFileFromRaw(file, contentDir, raw)
+}
+
+/**
+ * Async variant of `parseContentFile`. Uses `fs/promises.readFile` so multiple
+ * calls can be awaited concurrently via `Promise.all`, overlapping disk I/O.
+ */
+export async function parseContentFileAsync(
+  file: ContentFile,
+  contentDir: string,
+): Promise<ContentItem> {
+  const raw = await readFile(file.filePath, 'utf-8')
+  return parseContentFileFromRaw(file, contentDir, raw)
+}
+
+/**
+ * Strips body-only fields to produce a lean `ContentMeta` for the manifest.
+ */
+export function toContentMeta(item: ContentItem): ContentMeta {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const { _file, body, toc, excerpt, ...meta } = item
+  return meta as ContentMeta
+}

package/src/plugin/content/path-utils.ts

@@ -0,0 +1,47 @@
+import { relative } from 'pathe'
+
+/**
+ * Maps a content file path to a `_path` URL path.
+ *
+ * Rules:
+ * - Strip the content dir prefix
+ * - Strip the file extension
+ * - Strip `/index` suffix (so blog/index.md → /blog)
+ * - Strip `YYYY-MM-DD-` date prefix from the final slug segment
+ *
+ * Examples:
+ *   index.md                → /
+ *   about.md                → /about
+ *   blog/index.md           → /blog
+ *   blog/2026-04-03-hello.md → /blog/hello
+ *   docs/getting-started.md  → /docs/getting-started
+ *   data/products.json       → /data/products
+ */
+export function fileToContentPath(filePath: string, contentDir: string): string {
+  // Get path relative to contentDir, strip extension
+  let rel = relative(contentDir, filePath)
+  rel = rel.replace(/\.(md|json)$/, '')
+
+  // Split into segments
+  const segments = rel.split('/')
+
+  // Strip date prefix (YYYY-MM-DD-) from the last segment
+  const last = segments[segments.length - 1]
+  const stripped = last.replace(/^\d{4}-\d{2}-\d{2}-/, '')
+  segments[segments.length - 1] = stripped
+
+  // Strip trailing 'index' segment (but keep bare 'index' → '/')
+  if (segments.length > 1 && segments[segments.length - 1] === 'index') {
+    segments.pop()
+  }
+
+  // If the only segment was 'index', produce root path
+  if (segments.length === 1 && segments[0] === 'index') {
+    return '/'
+  }
+
+  const path = '/' + segments.join('/')
+  return path.replace(/\/+/g, '/')
+}
+
+

package/src/plugin/content/scanner.ts

@@ -0,0 +1,26 @@
+import fg from 'fast-glob'
+
+export interface ContentFile {
+  /** Absolute file path */
+  filePath: string
+  /** Extension without dot: 'md' | 'json' */
+  ext: 'md' | 'json'
+}
+
+/**
+ * Scans the content directory for all Markdown and JSON files.
+ * Returns absolute file paths sorted alphabetically.
+ */
+export async function scanContentFiles(contentDir: string): Promise<ContentFile[]> {
+  const files = await fg('**/*.{md,json}', {
+    cwd: contentDir,
+    absolute: true,
+    onlyFiles: true,
+    ignore: ['**/node_modules/**', '**/.git/**'],
+  })
+
+  return files.sort().map((filePath) => ({
+    filePath,
+    ext: filePath.endsWith('.json') ? 'json' : 'md',
+  }))
+}

package/src/plugin/content/search.ts

@@ -0,0 +1,28 @@
+import MiniSearch from 'minisearch'
+import type { ContentItem } from '../../types/content.js'
+
+/**
+ * Builds and serialises a MiniSearch full-text search index over `title` and `description`.
+ *
+ * Stored fields: `_path`, `title`, `description` — match `ContentSearchResult` exactly.
+ * Returns the serialised index as a JSON string ready to be written to `search-index.json`.
+ */
+export function buildSearchIndex(items: ContentItem[]): string {
+  const index = new MiniSearch({
+    fields: ['title', 'description'],
+    storeFields: ['_path', 'title', 'description'],
+    idField: '_path',
+  })
+
+  const docs = items
+    .filter((item) => item.title !== undefined)
+    .map((item) => ({
+      _path: item._path,
+      title: (item.title as string) ?? '',
+      description: (item.description as string) ?? '',
+    }))
+
+  index.addAll(docs)
+
+  return JSON.stringify(index)
+}

package/src/plugin/dts-generator.ts

@@ -76,7 +76,7 @@ const RUNTIME_GLOBALS = [
 
 const DIRECTIVE_GLOBALS = ['when', 'each', 'match', 'anchorBlock']
 
-const FRAMEWORK_GLOBALS = ['useHead', 'usePageData', 'useInject', 'useRuntimeConfig', 'defineMiddleware', 'defineServerMiddleware', 'useSeoMeta', 'useCookie', 'useSession', 'useAuth', 'useFetch', 'useRoute', 'navigateTo', 'useState', 'useLocale']
+const FRAMEWORK_GLOBALS = ['useHead', 'usePageData', 'useInject', 'useRuntimeConfig', 'defineMiddleware', 'defineServerMiddleware', 'useSeoMeta', 'useCookie', 'useSession', 'useAuth', 'useFetch', 'useRoute', 'navigateTo', 'useState', 'useLocale', 'queryContent', 'useContentSearch']
 
 /**
  * Scans a composables directory and returns a map of export name → file path.
@@ -146,6 +146,12 @@ export async function generateAutoImportDts(
     }
   }
 
+  lines.push('')
+  lines.push('  // Content layer types')
+  lines.push(`  type ContentMeta = import('@jasonshimmy/vite-plugin-cer-app')['ContentMeta']`)
+  lines.push(`  type ContentItem = import('@jasonshimmy/vite-plugin-cer-app')['ContentItem']`)
+  lines.push(`  type ContentHeading = import('@jasonshimmy/vite-plugin-cer-app')['ContentHeading']`)
+  lines.push(`  type ContentSearchResult = import('@jasonshimmy/vite-plugin-cer-app')['ContentSearchResult']`)
   lines.push('')
   lines.push('  // SSR loader data injected as window.__CER_DATA__ by the server.')
   lines.push('  // Consumed once by usePageData() during client hydration.')
@@ -155,6 +161,9 @@ export async function generateAutoImportDts(
   lines.push('  // Pre-populates the client useState() Map on first use.')
   lines.push('  // eslint-disable-next-line @typescript-eslint/no-explicit-any')
   lines.push('  var __CER_STATE_INIT__: any')
+  lines.push('  // App config injected by virtual:cer-app-config at app bootstrap.')
+  lines.push('  // eslint-disable-next-line @typescript-eslint/no-explicit-any')
+  lines.push('  var __CER_APP_CONFIG__: any')
   lines.push('}')
   lines.push('')
 

package/src/plugin/index.ts

@@ -19,6 +19,7 @@ import { generateServerMiddlewareCode } from './virtual/server-middleware.js'
 import { generateLoadingCode } from './virtual/loading.js'
 import { generateErrorCode } from './virtual/error.js'
 import { createWatcher } from './scanner.js'
+import { cerContent } from './content/index.js'
 
 // Virtual module IDs (raw)
 const VIRTUAL_IDS = {
@@ -181,7 +182,8 @@ function generateAppConfigModule(config: ResolvedCerConfig, ssr = false): string
     `export const runtimeConfig = { public: ${JSON.stringify(publicConfig, null, 2)} }\n` +
     `\n` +
     `export const i18nConfig = ${i18nValue}\n` +
-    `;(globalThis).__CER_I18N_CONFIG__ = i18nConfig\n`
+    `;(globalThis).__CER_I18N_CONFIG__ = i18nConfig\n` +
+    `;(globalThis).__CER_APP_CONFIG__ = appConfig\n`
 
   if (ssr) {
     const privateDefaults = config.runtimeConfig.private
@@ -521,5 +523,8 @@ export function cerApp(userConfig: CerAppConfig = {}): Plugin[] {
     cerAppPlugin,
     ...jitPlugins,
     ...(userConfig.autoImports?.components !== false ? [componentImportsProxy] : []),
+    cerContent(
+      userConfig.content,
+    ),
   ]
 }

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

@@ -71,6 +71,8 @@ const FRAMEWORK_MAP: Record<string, string> = {
   navigateTo: '@jasonshimmy/vite-plugin-cer-app/composables',
   useState: '@jasonshimmy/vite-plugin-cer-app/composables',
   useLocale: '@jasonshimmy/vite-plugin-cer-app/composables',
+  queryContent: '@jasonshimmy/vite-plugin-cer-app/composables',
+  useContentSearch: '@jasonshimmy/vite-plugin-cer-app/composables',
 }
 
 // All identifier maps — processed in order. Earlier maps take precedence for

package/src/runtime/composables/index.ts

@@ -22,3 +22,6 @@ export { navigateTo } from './use-navigate.js'
 export { useState } from './use-state.js'
 export { useLocale } from './use-locale.js'
 export type { LocaleComposable } from './use-locale.js'
+export { queryContent, QueryBuilder } from './use-content.js'
+export { useContentSearch } from './use-content-search.js'
+export type { UseContentSearchReturn } from './use-content-search.js'