@jasonshimmy/vite-plugin-cer-app 0.1.6 → 0.2.0

package/src/__tests__/plugin/build-ssr.test.ts

@@ -6,11 +6,16 @@ import { resolve } from 'pathe'
 // The `buildSSR` function itself invokes Vite's `build` API which we don't
 // need to exercise in unit tests (it's an integration concern).
 vi.mock('vite', () => ({ build: vi.fn().mockResolvedValue(undefined) }))
+vi.mock('../../plugin/generated-dir.js', () => ({
+  writeGeneratedDir: vi.fn(),
+  getGeneratedDir: vi.fn().mockReturnValue('/project/.cer'),
+  GENERATED_DIR_NAME: '.cer',
+}))
 // Partial mock: keep the real readFileSync/existsSync but allow overrides in
 // individual describe blocks if needed.
 vi.mock('node:fs', async (importOriginal) => {
   const actual = await importOriginal<typeof import('node:fs')>()
-  return { ...actual, existsSync: vi.fn().mockReturnValue(true) }
+  return { ...actual, existsSync: vi.fn().mockReturnValue(true), renameSync: vi.fn() }
 })
 
 import type { ResolvedCerConfig } from '../../plugin/dev-server.js'
@@ -202,24 +207,33 @@ describe('buildSSR — resolveClientEntry fallbacks', () => {
   })
 
   it('uses index.html when it exists', async () => {
-    existsSyncMock.mockReturnValue(true) // index.html exists
+    existsSyncMock.mockImplementation((p: unknown) => String(p).endsWith('index.html'))
     await buildSSR(makeConfig())
-    const clientInput = (buildMock.mock.calls[0][0] as any).build.rollupOptions.input
-    expect(clientInput).toMatch(/index\.html$/)
+    const clientInput = (buildMock.mock.calls[0][0] as Record<string, unknown>)
+    expect(((clientInput.build as Record<string, unknown>).rollupOptions as Record<string, unknown>).input).toMatch(/(?<!\.cer\/)index\.html$/)
   })
 
-  it('falls back to entry-client.ts when index.html is absent', async () => {
+  it('falls back to .cer/index.html when root index.html is absent', async () => {
+    existsSyncMock.mockImplementation((p: unknown) =>
+      String(p).endsWith('.cer/index.html'),
+    )
+    await buildSSR(makeConfig())
+    const clientInput = (buildMock.mock.calls[0][0] as Record<string, unknown>)
+    expect(((clientInput.build as Record<string, unknown>).rollupOptions as Record<string, unknown>).input).toMatch(/\.cer\/index\.html$/)
+  })
+
+  it('falls back to entry-client.ts when no index.html exists', async () => {
     existsSyncMock.mockImplementation((p: unknown) => String(p).endsWith('entry-client.ts'))
     await buildSSR(makeConfig())
-    const clientInput = (buildMock.mock.calls[0][0] as any).build.rollupOptions.input
-    expect(clientInput).toMatch(/entry-client\.ts$/)
+    const clientInput = (buildMock.mock.calls[0][0] as Record<string, unknown>)
+    expect(((clientInput.build as Record<string, unknown>).rollupOptions as Record<string, unknown>).input).toMatch(/entry-client\.ts$/)
   })
 
-  it('falls back to app.ts when neither index.html nor entry-client.ts exist', async () => {
+  it('falls back to app.ts when nothing else exists', async () => {
     existsSyncMock.mockReturnValue(false)
     await buildSSR(makeConfig())
-    const clientInput = (buildMock.mock.calls[0][0] as any).build.rollupOptions.input
-    expect(clientInput).toMatch(/app\.ts$/)
+    const clientInput = (buildMock.mock.calls[0][0] as Record<string, unknown>)
+    expect(((clientInput.build as Record<string, unknown>).rollupOptions as Record<string, unknown>).input).toMatch(/app\.ts$/)
   })
 })
 

package/src/__tests__/plugin/cer-app-plugin.test.ts

@@ -3,6 +3,10 @@ import { vi, describe, it, expect, beforeEach } from 'vitest'
 vi.mock('@jasonshimmy/custom-elements-runtime/vite-plugin', () => ({
   cerPlugin: vi.fn().mockReturnValue([{ name: 'cer-runtime-plugin' }]),
 }))
+vi.mock('node:fs', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:fs')>()
+  return { ...actual, existsSync: vi.fn().mockReturnValue(true), readFileSync: vi.fn().mockReturnValue('') }
+})
 vi.mock('../../plugin/dev-server.js', () => ({
   configureCerDevServer: vi.fn().mockResolvedValue(undefined),
 }))
@@ -15,6 +19,11 @@ vi.mock('../../plugin/dts-generator.js', () => ({
   writeAutoImportDts: vi.fn().mockResolvedValue(undefined),
   writeTsconfigPaths: vi.fn(),
 }))
+vi.mock('../../plugin/generated-dir.js', () => ({
+  writeGeneratedDir: vi.fn(),
+  getGeneratedDir: vi.fn().mockReturnValue('/project/.cer'),
+  GENERATED_DIR_NAME: '.cer',
+}))
 vi.mock('../../plugin/virtual/routes.js', () => ({ generateRoutesCode: vi.fn().mockResolvedValue('// routes') }))
 vi.mock('../../plugin/virtual/layouts.js', () => ({ generateLayoutsCode: vi.fn().mockResolvedValue('// layouts') }))
 vi.mock('../../plugin/virtual/components.js', () => ({ generateComponentsCode: vi.fn().mockResolvedValue('// components') }))
@@ -263,6 +272,16 @@ describe('cerApp plugin — transform hook', () => {
 })
 
 describe('cerApp plugin — buildStart hook', () => {
+  it('calls writeGeneratedDir on build start', async () => {
+    const { writeGeneratedDir } = await import('../../plugin/generated-dir.js')
+    vi.mocked(writeGeneratedDir).mockClear()
+    const plugin = getCerPlugin()
+    plugin.config({ root: '/project' }, { command: 'build', mode: 'production' })
+    plugin.configResolved(FAKE_RESOLVED)
+    await plugin.buildStart()
+    expect(writeGeneratedDir).toHaveBeenCalledTimes(1)
+  })
+
   it('calls scanComposableExports on build start', async () => {
     const { scanComposableExports } = await import('../../plugin/dts-generator.js')
     vi.mocked(scanComposableExports).mockClear()
@@ -295,6 +314,22 @@ describe('cerApp plugin — buildStart hook', () => {
 })
 
 describe('cerApp plugin — configureServer hook', () => {
+  it('calls writeGeneratedDir on server configure', async () => {
+    const { writeGeneratedDir } = await import('../../plugin/generated-dir.js')
+    vi.mocked(writeGeneratedDir).mockClear()
+    const plugin = getCerPlugin()
+    plugin.config({ root: '/project' }, { command: 'serve', mode: 'development' })
+    plugin.configResolved(FAKE_RESOLVED)
+    const mockServer = {
+      watcher: { on: vi.fn() },
+      moduleGraph: { getModuleById: vi.fn().mockReturnValue(null), invalidateModule: vi.fn() },
+      ws: { send: vi.fn() },
+      middlewares: { use: vi.fn() },
+    }
+    await plugin.configureServer(mockServer)
+    expect(writeGeneratedDir).toHaveBeenCalledTimes(1)
+  })
+
   it('calls scanComposableExports on server configure', async () => {
     const { scanComposableExports } = await import('../../plugin/dts-generator.js')
     vi.mocked(scanComposableExports).mockClear()

package/src/__tests__/plugin/dts-generator.test.ts

@@ -6,10 +6,12 @@ vi.mock('node:fs', async (importOriginal) => {
     ...actual,
     existsSync: vi.fn().mockReturnValue(false),
     writeFileSync: vi.fn(),
+    mkdirSync: vi.fn(),
     readFileSync: vi.fn().mockReturnValue(''),
   }
 })
 vi.mock('../../plugin/scanner.js', () => ({ scanDirectory: vi.fn().mockResolvedValue([]) }))
+vi.mock('../../plugin/generated-dir.js', () => ({ GENERATED_DIR_NAME: '.cer' }))
 
 import { existsSync, writeFileSync, readFileSync } from 'node:fs'
 import { scanDirectory } from '../../plugin/scanner.js'
@@ -32,10 +34,10 @@ beforeEach(() => {
 })
 
 describe('writeTsconfigPaths', () => {
-  it('writes cer-tsconfig.json to the root directory', () => {
+  it('writes tsconfig.json to the .cer directory', () => {
     writeTsconfigPaths(ROOT, `${ROOT}/app`)
     expect(writeFileSync).toHaveBeenCalledWith(
-      `${ROOT}/cer-tsconfig.json`,
+      `${ROOT}/.cer/tsconfig.json`,
       expect.any(String),
       'utf-8',
     )
@@ -65,6 +67,13 @@ describe('writeTsconfigPaths', () => {
     const json = JSON.parse(content)
     expect(json).toHaveProperty('compilerOptions.paths')
   })
+
+  it('includes project source directories in include array', () => {
+    writeTsconfigPaths(ROOT, `${ROOT}/app`)
+    const content = vi.mocked(writeFileSync).mock.calls[0][1] as string
+    const json = JSON.parse(content) as { include?: string[] }
+    expect(Array.isArray(json.include)).toBe(true)
+  })
 })
 
 describe('scanComposableExports', () => {
@@ -227,16 +236,16 @@ describe('generateVirtualModuleDts', () => {
 })
 
 describe('writeAutoImportDts', () => {
-  it('writes cer-auto-imports.d.ts to root', async () => {
+  it('writes auto-imports.d.ts to .cer/', async () => {
     await writeAutoImportDts(ROOT, COMPOSABLES_DIR)
     const paths = vi.mocked(writeFileSync).mock.calls.map(([p]) => String(p))
-    expect(paths.some(p => p.includes('cer-auto-imports.d.ts'))).toBe(true)
+    expect(paths.some(p => p.includes('.cer/auto-imports.d.ts'))).toBe(true)
   })
 
-  it('writes cer-env.d.ts to root', async () => {
+  it('writes env.d.ts to .cer/', async () => {
     await writeAutoImportDts(ROOT, COMPOSABLES_DIR)
     const paths = vi.mocked(writeFileSync).mock.calls.map(([p]) => String(p))
-    expect(paths.some(p => p.includes('cer-env.d.ts'))).toBe(true)
+    expect(paths.some(p => p.includes('.cer/env.d.ts'))).toBe(true)
   })
 
   it('writes exactly two files', async () => {

package/src/__tests__/plugin/generated-dir.test.ts

@@ -0,0 +1,168 @@
+import { vi, describe, it, expect, beforeEach } from 'vitest'
+
+vi.mock('node:fs', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:fs')>()
+  return {
+    ...actual,
+    existsSync: vi.fn().mockReturnValue(false),
+    writeFileSync: vi.fn(),
+    mkdirSync: vi.fn(),
+    readFileSync: vi.fn().mockReturnValue(''),
+    appendFileSync: vi.fn(),
+  }
+})
+vi.mock('../../runtime/app-template.js', () => ({ APP_ENTRY_TEMPLATE: '// app template' }))
+
+import { existsSync, writeFileSync, mkdirSync, readFileSync, appendFileSync } from 'node:fs'
+import {
+  GENERATED_DIR_NAME,
+  getGeneratedDir,
+  resolveAppEntry,
+  resolveHtmlEntry,
+  generateDefaultHtml,
+  writeGeneratedDir,
+} from '../../plugin/generated-dir.js'
+
+const ROOT = '/project'
+const mockConfig = {
+  root: ROOT,
+  srcDir: `${ROOT}/app`,
+} as Parameters<typeof writeGeneratedDir>[0]
+
+beforeEach(() => {
+  vi.mocked(existsSync).mockReturnValue(false)
+  vi.mocked(writeFileSync).mockClear()
+  vi.mocked(mkdirSync).mockClear()
+  vi.mocked(readFileSync).mockReturnValue('')
+  vi.mocked(appendFileSync).mockClear()
+})
+
+describe('GENERATED_DIR_NAME', () => {
+  it('is .cer', () => {
+    expect(GENERATED_DIR_NAME).toBe('.cer')
+  })
+})
+
+describe('getGeneratedDir', () => {
+  it('returns <root>/.cer', () => {
+    expect(getGeneratedDir(ROOT)).toBe(`${ROOT}/.cer`)
+  })
+})
+
+describe('resolveAppEntry', () => {
+  it('returns user app/app.ts when it exists', () => {
+    vi.mocked(existsSync).mockReturnValue(true)
+    expect(resolveAppEntry(mockConfig)).toBe(`${ROOT}/app/app.ts`)
+  })
+
+  it('returns .cer/app.ts when user app/app.ts is absent', () => {
+    vi.mocked(existsSync).mockReturnValue(false)
+    expect(resolveAppEntry(mockConfig)).toBe(`${ROOT}/.cer/app.ts`)
+  })
+})
+
+describe('resolveHtmlEntry', () => {
+  it('returns user index.html when it exists', () => {
+    vi.mocked(existsSync).mockReturnValue(true)
+    expect(resolveHtmlEntry(mockConfig)).toBe(`${ROOT}/index.html`)
+  })
+
+  it('returns .cer/index.html when user index.html is absent', () => {
+    vi.mocked(existsSync).mockReturnValue(false)
+    expect(resolveHtmlEntry(mockConfig)).toBe(`${ROOT}/.cer/index.html`)
+  })
+})
+
+describe('generateDefaultHtml', () => {
+  it('references /app/app.ts when user entry exists', () => {
+    vi.mocked(existsSync).mockReturnValue(true)
+    const html = generateDefaultHtml(mockConfig)
+    expect(html).toContain('/app/app.ts')
+    expect(html).not.toContain('/.cer/app.ts')
+  })
+
+  it('references /.cer/app.ts when user entry is absent', () => {
+    vi.mocked(existsSync).mockReturnValue(false)
+    const html = generateDefaultHtml(mockConfig)
+    expect(html).toContain('/.cer/app.ts')
+  })
+
+  it('includes <cer-layout-view> mount point', () => {
+    const html = generateDefaultHtml(mockConfig)
+    expect(html).toContain('<cer-layout-view>')
+  })
+
+  it('is valid HTML with doctype', () => {
+    const html = generateDefaultHtml(mockConfig)
+    expect(html).toContain('<!DOCTYPE html>')
+  })
+})
+
+describe('writeGeneratedDir', () => {
+  it('creates the .cer directory when absent', () => {
+    // existsSync returns false for everything → dir is created
+    writeGeneratedDir(mockConfig)
+    expect(mkdirSync).toHaveBeenCalledWith(`${ROOT}/.cer`, { recursive: true })
+  })
+
+  it('does not re-create the directory when it already exists', () => {
+    // existsSync returns true → dir already present
+    vi.mocked(existsSync).mockReturnValue(true)
+    writeGeneratedDir(mockConfig)
+    expect(mkdirSync).not.toHaveBeenCalled()
+  })
+
+  it('writes .cer/app.ts when app/app.ts does not exist', () => {
+    // Only the .cer dir check needs to return true to skip mkdirSync — but we
+    // want the user entry check to return false. Use a counter.
+    let callCount = 0
+    vi.mocked(existsSync).mockImplementation(() => {
+      callCount++
+      // First call: .cer/ dir → true (already exists, skip mkdir)
+      // Second call: app/app.ts → false (absent, write template)
+      // Subsequent calls: false (no .gitignore)
+      return callCount === 1
+    })
+    writeGeneratedDir(mockConfig)
+    const paths = vi.mocked(writeFileSync).mock.calls.map(([p]) => String(p))
+    expect(paths.some(p => p.endsWith('/.cer/app.ts'))).toBe(true)
+  })
+
+  it('skips writing .cer/app.ts when app/app.ts exists', () => {
+    // existsSync always returns true — dir exists, user entry exists
+    vi.mocked(existsSync).mockReturnValue(true)
+    writeGeneratedDir(mockConfig)
+    const paths = vi.mocked(writeFileSync).mock.calls.map(([p]) => String(p))
+    expect(paths.some(p => p.endsWith('/.cer/app.ts'))).toBe(false)
+  })
+
+  it('always writes .cer/index.html', () => {
+    writeGeneratedDir(mockConfig)
+    const paths = vi.mocked(writeFileSync).mock.calls.map(([p]) => String(p))
+    expect(paths.some(p => p.endsWith('/.cer/index.html'))).toBe(true)
+  })
+
+  it('creates .gitignore when absent', () => {
+    // existsSync returns false → .cer/ dir created, app.ts written, .gitignore created
+    writeGeneratedDir(mockConfig)
+    const paths = vi.mocked(writeFileSync).mock.calls.map(([p]) => String(p))
+    expect(paths.some(p => p.endsWith('/.gitignore'))).toBe(true)
+  })
+
+  it('appends .cer/ to existing .gitignore that does not contain it', () => {
+    // .gitignore exists (readFileSync returns '' — no .cer/ entry)
+    vi.mocked(existsSync).mockImplementation((p) => String(p).endsWith('.gitignore'))
+    vi.mocked(readFileSync).mockReturnValue('node_modules/\ndist/\n')
+    writeGeneratedDir(mockConfig)
+    expect(appendFileSync).toHaveBeenCalled()
+    const appendArg = vi.mocked(appendFileSync).mock.calls[0][1] as string
+    expect(appendArg).toContain('.cer/')
+  })
+
+  it('does not append to .gitignore when .cer/ is already present', () => {
+    vi.mocked(existsSync).mockImplementation((p) => String(p).endsWith('.gitignore'))
+    vi.mocked(readFileSync).mockReturnValue('node_modules/\n.cer/\ndist/\n')
+    writeGeneratedDir(mockConfig)
+    expect(appendFileSync).not.toHaveBeenCalled()
+  })
+})

package/src/cli/commands/build.ts

@@ -1,11 +1,12 @@
 import { Command } from 'commander'
 import { build } from 'vite'
-import { resolve } from 'pathe'
+import { resolve, join } from 'pathe'
 import { pathToFileURL } from 'node:url'
-import { existsSync } from 'node:fs'
+import { existsSync, renameSync } from 'node:fs'
 import { cerApp, resolveConfig } from '../../plugin/index.js'
-import { buildSSR } from '../../plugin/build-ssr.js'
+import { buildSSR, resolveClientEntry } from '../../plugin/build-ssr.js'
 import { buildSSG } from '../../plugin/build-ssg.js'
+import { writeGeneratedDir } from '../../plugin/generated-dir.js'
 import type { CerAppConfig } from '../../types/config.js'
 
 async function loadCerConfig(root: string): Promise<CerAppConfig> {
@@ -73,15 +74,28 @@ export function buildCommand(): Command {
 
       switch (config.mode) {
         case 'spa': {
-          // Standard Vite build — single-page app
+          // Write .cer/ files BEFORE resolveClientEntry checks for .cer/index.html.
+          writeGeneratedDir(config)
+          const spaEntry = resolveClientEntry(config)
+          const spaOutDir = resolve(root, 'dist')
           await build({
             root,
             plugins: cerApp(userConfig),
             build: {
-              outDir: resolve(root, 'dist'),
+              outDir: spaOutDir,
+              rollupOptions: { input: spaEntry },
             },
           })
+          // If the entry was .cer/index.html, Vite outputs it as dist/.cer/index.html.
+          // Rename it to dist/index.html so the preview server can find it.
+          const generatedHtmlOut = join(spaOutDir, '.cer/index.html')
+          const rootHtmlOut = join(spaOutDir, 'index.html')
+          if (existsSync(generatedHtmlOut) && !existsSync(rootHtmlOut)) {
+            renameSync(generatedHtmlOut, rootHtmlOut)
+          }
           console.log('[cer-app] SPA build complete.')
+          // Force exit: Vite HTML builds may keep Node timers alive.
+          process.exit(0)
           break
         }
 

package/src/cli/commands/dev.ts

@@ -3,7 +3,7 @@ import { createServer } from 'vite'
 import { resolve } from 'pathe'
 import { pathToFileURL } from 'node:url'
 import { existsSync } from 'node:fs'
-import { cerApp, resolveConfig } from '../../plugin/index.js'
+import { cerApp } from '../../plugin/index.js'
 import type { CerAppConfig } from '../../types/config.js'
 
 /**
@@ -28,7 +28,7 @@ async function loadCerConfig(root: string): Promise<CerAppConfig> {
   try {
     // Use Vite's build to transpile TS config at runtime
     const { build } = await import('vite')
-    const result = await build({
+    await build({
       build: {
         lib: {
           entry: filePath,

package/src/cli/commands/preview.ts

@@ -107,9 +107,10 @@ export function previewCommand(): Command {
         console.log('[cer-app] Starting SSR preview server...')
 
         // Load the server bundle
+        type SsrHandlerFn = (req: IncomingMessage, res: ServerResponse) => void | Promise<void>
         let serverMod: {
-          handler?: Function
-          default?: Function
+          handler?: SsrHandlerFn
+          default?: SsrHandlerFn
           apiRoutes?: Array<{ path: string; handlers: Record<string, unknown> }>
         }
         try {
@@ -151,10 +152,11 @@ export function previewCommand(): Command {
                 }
                 augRes.status = function (code) { this.statusCode = code; return this }
 
+                type ApiHandlerFn = (req: typeof augReq, res: typeof augRes) => void | Promise<void>
                 const handlerFn =
-                  (route.handlers[method.toLowerCase()] as Function | undefined) ??
-                  (route.handlers[method.toUpperCase()] as Function | undefined) ??
-                  (route.handlers['default'] as Function | undefined)
+                  (route.handlers[method.toLowerCase()] as ApiHandlerFn | undefined) ??
+                  (route.handlers[method.toUpperCase()] as ApiHandlerFn | undefined) ??
+                  (route.handlers['default'] as ApiHandlerFn | undefined)
 
                 if (typeof handlerFn === 'function') {
                   try {

package/src/plugin/build-ssg.ts

@@ -1,7 +1,7 @@
 import { writeFile, mkdir } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { join } from 'pathe'
-import { createServer, build, type UserConfig } from 'vite'
+import { createServer, type UserConfig } from 'vite'
 import type { ResolvedCerConfig } from './dev-server.js'
 import { buildSSR } from './build-ssr.js'
 import { buildRouteEntry } from './path-utils.js'
@@ -138,7 +138,7 @@ async function renderPath(
       setHeader: () => {},
       end: (body: string) => resolve(body),
     }
-    ;(handlerFn as Function)(mockReq, mockRes).catch(reject)
+    ;(handlerFn as (req: unknown, res: unknown) => Promise<void>)(mockReq, mockRes).catch(reject)
   })
 }
 

package/src/plugin/build-ssr.ts

@@ -1,22 +1,23 @@
 import { build, type UserConfig } from 'vite'
 import { join, resolve } from 'pathe'
-import { existsSync } from 'node:fs'
+import { existsSync, renameSync } from 'node:fs'
 import type { ResolvedCerConfig } from './dev-server.js'
+import { getGeneratedDir, writeGeneratedDir } from './generated-dir.js'
 
 /**
  * Resolves the client build entry point for an SSR/SSG build.
  *
  * Priority order:
- * 1. `index.html` at the project root — preferred because Vite writes a
- *    processed `index.html` to `dist/client/` with correct asset references,
- *    which `renderPath` then uses as the shell template for SSG pages.
- * 2. `app/entry-client.ts` — fallback for projects that handle HTML injection
- *    themselves (e.g. a custom Express server).
- * 3. `app/app.ts` — last resort (same bundle, no DSD hydration preamble).
+ * 1. `index.html` at the project root — consumer-provided HTML shell.
+ * 2. `.cer/index.html` — auto-generated HTML shell (Nuxt-style magic).
+ * 3. `app/entry-client.ts` — fallback for projects that manage HTML externally.
+ * 4. `app/app.ts` — last resort (same bundle, no DSD hydration preamble).
  */
-function resolveClientEntry(config: ResolvedCerConfig): string {
+export function resolveClientEntry(config: ResolvedCerConfig): string {
   const indexHtml = resolve(config.root, 'index.html')
   if (existsSync(indexHtml)) return indexHtml
+  const cerIndexHtml = join(getGeneratedDir(config.root), 'index.html')
+  if (existsSync(cerIndexHtml)) return cerIndexHtml
   const entryClient = resolve(config.srcDir, 'entry-client.ts')
   if (existsSync(entryClient)) return entryClient
   return resolve(config.srcDir, 'app.ts')
@@ -225,6 +226,10 @@ export async function buildSSR(
   const clientOutDir = join(config.root, 'dist/client')
   const serverOutDir = join(config.root, 'dist/server')
 
+  // Write .cer/ generated files BEFORE resolving the client entry so that
+  // .cer/index.html is on disk when resolveClientEntry checks for it.
+  writeGeneratedDir(config)
+
   // Resolve the client entry — index.html is preferred so Vite writes a
   // processed index.html to dist/client/ for use as the SSG shell template.
   const clientEntry = resolveClientEntry(config)
@@ -244,6 +249,15 @@ export async function buildSSR(
     },
   })
 
+  // If the client entry was .cer/index.html, Vite outputs it as
+  // dist/client/.cer/index.html (preserving relative path). The SSR server
+  // template expects dist/client/index.html, so rename it into place.
+  const generatedHtmlOut = join(clientOutDir, '.cer/index.html')
+  const rootHtmlOut = join(clientOutDir, 'index.html')
+  if (existsSync(generatedHtmlOut) && !existsSync(rootHtmlOut)) {
+    renameSync(generatedHtmlOut, rootHtmlOut)
+  }
+
   // Generate server entry source inline via a virtual plugin
   const serverEntryCode = generateServerEntryCode()
   const VIRTUAL_SERVER_ENTRY = 'virtual:cer-server-entry'

package/src/plugin/dev-server.ts

@@ -186,11 +186,12 @@ export function configureCerDevServer(
 
         // Try to find a handler for the HTTP method. Exports may be GET/POST (uppercase)
         // or get/post (lowercase); try both plus a 'default' fallback.
+        type RouteHandlerFn = (req: typeof augmentedReq, res: typeof augmentedRes) => void | Promise<void>
         const handlerKey = method.toLowerCase()
         const handler =
-          (route.handlers[handlerKey] as Function | undefined) ??
-          (route.handlers[method.toUpperCase()] as Function | undefined) ??
-          (route.handlers['default'] as Function | undefined)
+          (route.handlers[handlerKey] as RouteHandlerFn | undefined) ??
+          (route.handlers[method.toUpperCase()] as RouteHandlerFn | undefined) ??
+          (route.handlers['default'] as RouteHandlerFn | undefined)
 
         if (typeof handler === 'function') {
           try {

package/src/plugin/dts-generator.ts

@@ -1,27 +1,46 @@
-import { writeFileSync } from 'node:fs'
-import { readFileSync, existsSync } from 'node:fs'
+import { writeFileSync, mkdirSync, existsSync } from 'node:fs'
+import { readFileSync } from 'node:fs'
 import { join, relative } from 'pathe'
 import { scanDirectory } from './scanner.js'
+import { GENERATED_DIR_NAME } from './generated-dir.js'
 
 /**
- * Writes `cer-tsconfig.json` to the project root containing path aliases for
- * the `~/` prefix. Users extend it from their `tsconfig.json`:
- *   { "extends": "./cer-tsconfig.json" }
+ * Writes `.cer/tsconfig.json` containing path aliases for the `~/` prefix
+ * plus include/exclude entries so the consumer's `tsconfig.json` only needs:
+ *   { "extends": "./.cer/tsconfig.json" }
  */
 export function writeTsconfigPaths(root: string, srcDir: string): void {
-  const rel = './' + relative(root, srcDir).replace(/\\/g, '/')
+  const cerDir = join(root, GENERATED_DIR_NAME)
+  if (!existsSync(cerDir)) {
+    mkdirSync(cerDir, { recursive: true })
+  }
+
+  // Paths are relative to .cer/ inside the project root, so prefix with ../
+  const srcRel = '../' + relative(root, srcDir).replace(/\\/g, '/')
   const paths: Record<string, string[]> = {
-    '~/*': [`${rel}/*`],
-    '~/pages/*': [`${rel}/pages/*`],
-    '~/layouts/*': [`${rel}/layouts/*`],
-    '~/components/*': [`${rel}/components/*`],
-    '~/composables/*': [`${rel}/composables/*`],
-    '~/plugins/*': [`${rel}/plugins/*`],
-    '~/middleware/*': [`${rel}/middleware/*`],
-    '~/assets/*': [`${rel}/assets/*`],
+    '~/*': [`${srcRel}/*`],
+    '~/pages/*': [`${srcRel}/pages/*`],
+    '~/layouts/*': [`${srcRel}/layouts/*`],
+    '~/components/*': [`${srcRel}/components/*`],
+    '~/composables/*': [`${srcRel}/composables/*`],
+    '~/plugins/*': [`${srcRel}/plugins/*`],
+    '~/middleware/*': [`${srcRel}/middleware/*`],
+    '~/assets/*': [`${srcRel}/assets/*`],
+  }
+
+  const tsconfig = {
+    compilerOptions: { paths },
+    include: [
+      '../app/**/*.ts',
+      '../server/**/*.ts',
+      './**/*.ts',
+      './**/*.d.ts',
+    ],
+    exclude: ['../node_modules', '../dist'],
   }
-  const content = JSON.stringify({ compilerOptions: { paths } }, null, 2) + '\n'
-  writeFileSync(join(root, 'cer-tsconfig.json'), content, 'utf-8')
+
+  const content = JSON.stringify(tsconfig, null, 2) + '\n'
+  writeFileSync(join(cerDir, 'tsconfig.json'), content, 'utf-8')
 }
 
 const RUNTIME_GLOBALS = [
@@ -199,16 +218,21 @@ export async function generateVirtualModuleDts(
 }
 
 /**
- * Writes both `cer-auto-imports.d.ts` and `cer-env.d.ts` to the project root.
+ * Writes `auto-imports.d.ts` and `env.d.ts` to `.cer/` inside the project root.
  */
 export async function writeAutoImportDts(
   root: string,
   composablesDir: string,
   composableExports?: Map<string, string>,
 ): Promise<void> {
+  const cerDir = join(root, GENERATED_DIR_NAME)
+  if (!existsSync(cerDir)) {
+    mkdirSync(cerDir, { recursive: true })
+  }
+
   const scanned = composableExports ?? await scanComposableExports(composablesDir)
   const autoImportsContent = await generateAutoImportDts(root, composablesDir, scanned)
   const envContent = await generateVirtualModuleDts(root, composablesDir, scanned)
-  writeFileSync(join(root, 'cer-auto-imports.d.ts'), autoImportsContent, 'utf-8')
-  writeFileSync(join(root, 'cer-env.d.ts'), envContent, 'utf-8')
+  writeFileSync(join(cerDir, 'auto-imports.d.ts'), autoImportsContent, 'utf-8')
+  writeFileSync(join(cerDir, 'env.d.ts'), envContent, 'utf-8')
 }