fix(serve): serve static.source directories in dev

Closes #1876

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Author: cossssmin

src/build.ts

@@ -8,6 +8,7 @@ import { resolveConfig } from './config/index.ts'
 import { EventManager } from './events/index.ts'
 import { createRenderer } from './render/createRenderer.ts'
 import { normalizeComponentSources } from './utils/componentSources.ts'
+import { staticBase } from './utils/staticPaths.ts'
 import { buildTemplate, computeContentBase } from './render/buildTemplate.ts'
 import type { MaizzleConfig } from './types/index.ts'
 
@@ -262,10 +263,3 @@ async function copyStatic(config: MaizzleConfig, outputPath: string): Promise<vo
     cpSync(file, destPath)
   }
 }
-
-/** Absolute static (non-glob) prefix of a source pattern, used as the strip base. */
-function staticBase(pattern: string): string {
-  const staticPart = pattern.split(/[*{?[]/)[0]
-  // Treat both separators as trailing: resolved patterns use '\' on Windows.
-  return resolve(/[/\\]$/.test(staticPart) ? staticPart : dirname(staticPart))
-}

src/serve.ts

@@ -20,8 +20,10 @@ import { setActiveRenderer } from './render/active.ts'
 import { serveCompatibility } from './server/compatibility.ts'
 import { serveLint } from './server/linter.ts'
 import { sendEmail } from './server/email.ts'
+import { serveStaticFile } from './server/static.ts'
 import { normalizeComponentSources } from './utils/componentSources.ts'
 import { createWatchedFileMatcher, deriveWatchRoots } from './utils/watchPaths.ts'
+import { staticBase } from './utils/staticPaths.ts'
 import type { MaizzleConfig } from './types/index.ts'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
@@ -262,6 +264,34 @@ function maizzleDevPlugin(
 
       let isWatchedFile = applyWatchPaths(config)
 
+      /**
+       * Serve the `static.source` directories at `/<static.destination>`,
+       * mirroring what `build` copies to the output dir, so templates that
+       * reference `/images/logo.png` resolve in the preview iframe. Each
+       * positive pattern's glob-free prefix is mounted (looked up on disk
+       * per request, so files added after startup are served) and added
+       * to the watcher so the preview refreshes on changes. Runs again
+       * after a config reload; the middleware below reads the current
+       * mounts on every request.
+       */
+      const applyStaticMounts = (cfg: MaizzleConfig) => {
+        const sources = cfg.static?.source ?? ['public/**/*.*']
+        const destination = (cfg.static?.destination ?? 'public').replace(/^\/+|\/+$/g, '')
+        const prefix = destination ? `/${destination}` : ''
+        const bases = [...new Set(sources.filter(s => !s.startsWith('!')).map(staticBase))]
+
+        for (const base of bases) {
+          server.watcher.add(base)
+        }
+
+        return {
+          mounts: bases.map(base => ({ prefix, base })),
+          isStaticFile: createWatchedFileMatcher(sources, process.cwd()),
+        }
+      }
+
+      let { mounts: staticMounts, isStaticFile } = applyStaticMounts(config)
+
       /**
        * Serialize watcher work onto one chain. The change handler closes and
        * recreates the renderer across awaits; without serialization a second
@@ -281,6 +311,8 @@ function maizzleDevPlugin(
           await renderer.invalidateAll()
           bumpGeneration()
           server.ws.send({ type: 'custom', event: 'maizzle:templates-changed' })
+        } else if (isStaticFile(file)) {
+          server.ws.send({ type: 'custom', event: 'maizzle:template-updated', data: { file } })
         }
       }))
 
@@ -289,6 +321,8 @@ function maizzleDevPlugin(
           await renderer.invalidateAll()
           bumpGeneration()
           server.ws.send({ type: 'custom', event: 'maizzle:templates-changed' })
+        } else if (isStaticFile(file)) {
+          server.ws.send({ type: 'custom', event: 'maizzle:template-updated', data: { file } })
         }
       }))
 
@@ -313,6 +347,7 @@ function maizzleDevPlugin(
           // content, components.source, root, or server.watch values keep
           // emitting events without a server restart.
           isWatchedFile = applyWatchPaths(config)
+          ;({ mounts: staticMounts, isStaticFile } = applyStaticMounts(config))
 
           /**
            * Push UI-relevant config bits so the dev UI reacts to live edits
@@ -333,6 +368,7 @@ function maizzleDevPlugin(
         if (
           isTemplateFile(file)
           || isWatchedFile(file)
+          || isStaticFile(file)
         ) {
           server.ws.send({ type: 'custom', event: 'maizzle:template-updated', data: { file } })
         }
@@ -385,6 +421,19 @@ function maizzleDevPlugin(
         next()
       })
 
+      // Static assets from `static.source`, mounted at `/<static.destination>`
+      server.middlewares.use((req: any, res: any, next: any) => {
+        const url: string = req.url || '/'
+
+        for (const { prefix, base } of staticMounts) {
+          if (url === prefix || url.startsWith(`${prefix}/`) || url.startsWith(`${prefix}?`)) {
+            if (serveStaticFile(base, url.slice(prefix.length) || '/', res)) return
+          }
+        }
+
+        next()
+      })
+
       // Dev UI fallback (after Vite's middleware)
       return () => {
         server.middlewares.use(async (req: any, res: any, next: any) => {

src/server/static.ts

@@ -0,0 +1,66 @@
+import { createReadStream, statSync } from 'node:fs'
+import { extname, resolve, sep } from 'node:path'
+import type { ServerResponse } from 'node:http'
+
+const MIME: Record<string, string> = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+  '.bmp': 'image/bmp',
+  '.css': 'text/css',
+  '.js': 'text/javascript',
+  '.html': 'text/html',
+  '.txt': 'text/plain',
+  '.json': 'application/json',
+  '.pdf': 'application/pdf',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.otf': 'font/otf',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+  '.mp3': 'audio/mpeg',
+}
+
+/**
+ * Stream the file at `urlPath` (mount prefix already stripped) from
+ * `base`. Returns false when there is nothing to serve — missing file,
+ * directory, or a path escaping `base` — so the caller can fall through.
+ */
+export function serveStaticFile(base: string, urlPath: string, res: ServerResponse): boolean {
+  let pathname: string
+
+  try {
+    pathname = decodeURIComponent(urlPath.split('?')[0])
+  } catch {
+    return false
+  }
+
+  const file = resolve(base, `.${pathname}`)
+
+  if (file !== base && !file.startsWith(base + sep)) {
+    return false
+  }
+
+  let size: number
+
+  try {
+    const stat = statSync(file)
+    if (!stat.isFile()) return false
+    size = stat.size
+  } catch {
+    return false
+  }
+
+  res.setHeader('Content-Type', MIME[extname(file).toLowerCase()] ?? 'application/octet-stream')
+  res.setHeader('Content-Length', size)
+  res.setHeader('Cache-Control', 'no-cache')
+  createReadStream(file).pipe(res)
+
+  return true
+}

src/tests/serve.test.ts

@@ -27,6 +27,63 @@ describe('serve dev server', () => {
     rmSync(tempDir, { recursive: true, force: true })
   })
 
+  const baseUrl = () => server!.resolvedUrls!.local[0].replace(/\/$/, '')
+
+  it('serves static.source directories at /<static.destination>', async () => {
+    mkdirSync(join(tempDir, 'images'), { recursive: true })
+    writeFileSync(join(tempDir, 'images', 'logo.png'), 'png-bytes')
+
+    server = await serve({ config: { static: { source: ['images/**/*.*'], destination: 'images' } }, port: 3157, silent: true })
+
+    const res = await fetch(`${baseUrl()}/images/logo.png`)
+    expect(res.status).toBe(200)
+    expect(await res.text()).toBe('png-bytes')
+
+    expect((await fetch(`${baseUrl()}/images/missing.png`)).status).toBe(404)
+  }, 30000)
+
+  it('serves the default public/ directory at / and /public', async () => {
+    mkdirSync(join(tempDir, 'public'), { recursive: true })
+    writeFileSync(join(tempDir, 'public', 'logo.png'), 'png-bytes')
+
+    server = await serve({ port: 3157, silent: true })
+
+    expect((await fetch(`${baseUrl()}/logo.png`)).status).toBe(200)
+    expect((await fetch(`${baseUrl()}/public/logo.png`)).status).toBe(200)
+  }, 30000)
+
+  it('serves static files added after the server started', async () => {
+    server = await serve({ config: { static: { source: ['images/**/*.*'], destination: 'images' } }, port: 3157, silent: true })
+
+    mkdirSync(join(tempDir, 'images'), { recursive: true })
+    writeFileSync(join(tempDir, 'images', 'late.png'), 'late')
+
+    const res = await fetch(`${baseUrl()}/images/late.png`)
+    expect(res.status).toBe(200)
+    expect(await res.text()).toBe('late')
+  }, 30000)
+
+  it('re-mounts static directories when the config changes', async () => {
+    writeFileSync(join(tempDir, 'maizzle.config.js'), "export default { static: { source: ['images/**/*.*'], destination: 'images' } }\n")
+    mkdirSync(join(tempDir, 'images'), { recursive: true })
+    mkdirSync(join(tempDir, 'assets'), { recursive: true })
+    writeFileSync(join(tempDir, 'images', 'a.png'), 'a')
+    writeFileSync(join(tempDir, 'assets', 'b.png'), 'b')
+
+    server = await serve({ port: 3157, silent: true })
+
+    expect((await fetch(`${baseUrl()}/images/a.png`)).status).toBe(200)
+    expect((await fetch(`${baseUrl()}/assets/b.png`)).status).toBe(404)
+
+    writeFileSync(join(tempDir, 'maizzle.config.js'), "export default { static: { source: ['assets/**/*.*'], destination: 'assets' } }\n")
+    server.watcher.emit('change', resolve(tempDir, 'maizzle.config.js'))
+
+    await vi.waitFor(async () => {
+      expect((await fetch(`${baseUrl()}/assets/b.png`)).status).toBe(200)
+      expect((await fetch(`${baseUrl()}/images/a.png`)).status).toBe(404)
+    }, { timeout: 15000, interval: 100 })
+  }, 30000)
+
   it('refreshes the active renderer when the config file changes', async () => {
     writeFileSync(join(tempDir, 'maizzle.config.js'), 'export default {}\n')
 

src/utils/staticPaths.ts

@@ -0,0 +1,8 @@
+import { dirname, resolve } from 'node:path'
+
+/** Absolute static (non-glob) prefix of a source pattern, used as the strip base. */
+export function staticBase(pattern: string): string {
+  const staticPart = pattern.split(/[*{?[]/)[0]
+  // Treat both separators as trailing: resolved patterns use '\' on Windows.
+  return resolve(/[/\\]$/.test(staticPart) ? staticPart : dirname(staticPart))
+}