@inglorious/ssx 0.4.1 → 1.1.0

package/src/build/vite-config.js

@@ -0,0 +1,51 @@
+import path from "node:path"
+
+import { mergeConfig } from "vite"
+
+// import { minifyTemplateLiterals } from "rollup-plugin-minify-template-literals"
+
+/**
+ * Generate Vite config for building the client bundle
+ */
+export function createViteConfig(options = {}) {
+  const {
+    rootDir = "src",
+    outDir = "dist",
+    publicDir = "public",
+    vite = {},
+  } = options
+
+  return mergeConfig(
+    {
+      root: rootDir,
+      publicDir: path.resolve(process.cwd(), rootDir, publicDir),
+      // plugins: [minifyTemplateLiterals()], // TODO: minification breaks hydration. The footprint difference is minimal after all
+      build: {
+        outDir,
+        emptyOutDir: false, // Don't delete HTML files we already generated
+        rollupOptions: {
+          input: {
+            main: path.resolve(outDir, "main.js"),
+          },
+          output: {
+            entryFileNames: "[name].js",
+            chunkFileNames: "[name].[hash].js",
+            assetFileNames: "[name].[ext]",
+
+            manualChunks(id) {
+              if (id.includes("node_modules")) {
+                return "lib"
+              }
+            },
+          },
+        },
+      },
+      resolve: {
+        alias: {
+          "@": path.resolve(process.cwd(), rootDir),
+        },
+      },
+    },
+    vite,
+  )
+}

package/src/config.js

@@ -0,0 +1,16 @@
+import path from "node:path"
+import { pathToFileURL } from "node:url"
+
+export async function loadConfig(options) {
+  const { rootDir = "src", configPath = "site.config.js" } = options
+
+  try {
+    const config = await import(pathToFileURL(path.join(rootDir, configPath)))
+    return config.default || config
+  } catch (error) {
+    if (error.code === "MODULE_NOT_FOUND") {
+      return {} // Default config
+    }
+    throw error
+  }
+}

package/src/{dev.js → dev/index.js}

@@ -3,13 +3,18 @@ import path from "node:path"
 import connect from "connect"
 import { createServer } from "vite"
 
-import { renderPage } from "./render.js"
-import { getPages } from "./router.js"
-import { generateApp } from "./scripts/app.js"
-import { generateStore } from "./store.js"
+import { loadConfig } from "../config.js"
+import { renderPage } from "../render/index.js"
+import { getPages } from "../router/index.js"
+import { generateApp } from "../scripts/app.js"
+import { generateStore } from "../store.js"
+import { createViteConfig, virtualFiles } from "./vite-config.js"
 
 export async function dev(options = {}) {
-  const { rootDir = "src", port = 3000, renderOptions = {} } = options
+  const config = await loadConfig(options)
+
+  const mergedOptions = { ...config, ...options }
+  const { rootDir = "src" } = mergedOptions
 
   console.log("🚀 Starting dev server...\n")
 
@@ -18,20 +23,11 @@ export async function dev(options = {}) {
   console.log(`📄 Found ${pages.length} pages\n`)
 
   // Generate store config once for all pages
-  const store = await generateStore(pages, options)
+  const store = await generateStore(pages, mergedOptions)
 
   // Create Vite dev server
-  const viteServer = await createServer({
-    root: process.cwd(),
-    server: { port, middlewareMode: true },
-    appType: "custom",
-    plugins: [virtualPlugin()],
-    resolve: {
-      alias: {
-        "@": path.resolve(process.cwd(), rootDir),
-      },
-    },
-  })
+  const viteConfig = createViteConfig(mergedOptions)
+  const viteServer = await createServer(viteConfig)
 
   // Use Vite's middleware first (handles HMR, static files, etc.)
   const connectServer = connect()
@@ -43,14 +39,30 @@ export async function dev(options = {}) {
     const [url] = req.url.split("?")
 
     try {
+      // Skip special routes, static files, AND public assets
+      if (
+        url.startsWith("/@") ||
+        url.includes(".") || // Vite handles static files
+        url === "/favicon.ico"
+      ) {
+        return next() // Let Vite serve it
+      }
+
       // Find matching page
       const page = pages.find((p) => matchRoute(p.path, url))
       if (!page) return next()
 
       const module = await viteServer.ssrLoadModule(page.filePath)
-      const html = await renderPage(store, page, module, {
-        ...renderOptions,
+      page.module = module
+
+      const entity = store._api.getEntity(page.moduleName)
+      if (module.load) {
+        await module.load(entity, page)
+      }
+      const html = await renderPage(store, page, entity, {
+        ...mergedOptions,
         wrap: true,
+        isDev: true,
       })
 
       const app = generateApp(store, pages)
@@ -64,6 +76,7 @@ export async function dev(options = {}) {
     }
   })
 
+  const { port = 3000 } = viteConfig.server ?? {}
   const server = connectServer.listen(port)
 
   console.log(`\n✨ Dev server running at http://localhost:${port}\n`)
@@ -93,19 +106,3 @@ function matchRoute(pattern, url) {
     return part === urlParts[i]
   })
 }
-
-const virtualFiles = new Map()
-
-function virtualPlugin() {
-  return {
-    name: "ssx-virtual-files",
-
-    resolveId(id) {
-      if (virtualFiles.has(id)) return id
-    },
-
-    load(id) {
-      if (virtualFiles.has(id)) return virtualFiles.get(id)
-    },
-  }
-}

package/src/dev/vite-config.js

@@ -0,0 +1,40 @@
+import path from "node:path"
+
+import { mergeConfig } from "vite"
+
+export function createViteConfig(options = {}) {
+  const { rootDir = "src", publicDir = "public", vite = {} } = options
+  const { port = 3000 } = vite.dev ?? {}
+
+  return mergeConfig(
+    {
+      root: process.cwd(),
+      publicDir: path.resolve(process.cwd(), rootDir, publicDir),
+      server: { port, middlewareMode: true },
+      appType: "custom",
+      plugins: [virtualPlugin()],
+      resolve: {
+        alias: {
+          "@": path.resolve(process.cwd(), rootDir),
+        },
+      },
+    },
+    vite,
+  )
+}
+
+export const virtualFiles = new Map()
+
+function virtualPlugin() {
+  return {
+    name: "ssx-virtual-files",
+
+    resolveId(id) {
+      if (virtualFiles.has(id)) return id
+    },
+
+    load(id) {
+      if (virtualFiles.has(id)) return virtualFiles.get(id)
+    },
+  }
+}

package/src/module.js

@@ -1,8 +1,5 @@
-const RESERVED = ["title", "meta", "scripts", "styles", "load"]
-
 export function getModuleName(pageModule) {
   const name = Object.keys(pageModule).find((key) => {
-    if (RESERVED.includes(key)) return false
     const value = pageModule[key]
     return (
       value && typeof value === "object" && typeof value.render === "function"

package/src/page-options.js

@@ -0,0 +1,8 @@
+export function createGetPageOption(store, module, entity) {
+  let { metadata = {} } = module
+  if (typeof metadata === "function") {
+    metadata = metadata(entity, store._api)
+  }
+
+  return (name, defaults) => metadata[name] ?? defaults[name]
+}

package/src/{html.js → render/html.js}

@@ -2,6 +2,8 @@ import { html } from "@inglorious/web"
 import { render as ssrRender } from "@lit-labs/ssr"
 import { collectResult } from "@lit-labs/ssr/lib/render-result.js"
 
+import { layout as defaultLayout } from "./layout.js"
+
 export async function toHTML(store, renderFn, options = {}) {
   const api = { ...store._api }
   api.render = createRender(api)
@@ -17,7 +19,10 @@ export async function toHTML(store, renderFn, options = {}) {
     ? stripLitMarkers(resultString)
     : resultString
 
-  return options.wrap ? wrapHTML(finalHTML, options) : finalHTML
+  if (!options.wrap) return finalHTML
+
+  const layout = options.layout ?? defaultLayout
+  return options.wrap ? layout(finalHTML, options) : finalHTML
 }
 
 function stripLitMarkers(html) {
@@ -26,28 +31,7 @@ function stripLitMarkers(html) {
     .replace(/<!--\s*-->/g, "") // Empty comments
 }
 
-function wrapHTML(body, options) {
-  const { dev, title = "", meta = {}, styles = [], scripts = [] } = options
-
-  return `<!DOCTYPE html>
-<html>
-<head>
-  <meta charset="UTF-8">
-  <title>${title}</title>
-  ${Object.entries(meta)
-    .map(([name, content]) => `<meta name="${name}" content="${content}">`)
-    .join("\n")}
-  ${styles.map((href) => `<link rel="stylesheet" href="${href}">`).join("\n")}
-</head>
-<body>
-  <div id="root">${body}</div>
-
-  ${dev ? `<script type="module" src="/@vite/client"></script>` : ``}<script type="module" src="/main.js"></script>
-  ${scripts.map((src) => `<script type="module" src="${src}"></script>`).join("\n")}
-</body>
-</html>`
-}
-
+// TODO: this was copied from @inglorious/web, maybe expose it?
 function createRender(api) {
   return function (id, options = {}) {
     const entity = api.getEntity(id)

package/src/render/index.js

@@ -0,0 +1,43 @@
+import { createGetPageOption } from "../page-options.js"
+import { toHTML } from "./html.js"
+
+const DEFAULT_OPTIONS = {
+  lang: "en",
+  charset: "UTF-8",
+  title: "",
+  meta: {},
+  styles: [],
+  head: "",
+  scripts: [],
+}
+
+export async function renderPage(store, page, entity, options = {}) {
+  const { moduleName, module } = page
+
+  const getPageOption = createGetPageOption(store, module, entity)
+
+  const lang = getPageOption("lang", DEFAULT_OPTIONS) ?? options.lang
+  const charset = getPageOption("charset", DEFAULT_OPTIONS) ?? options.charset
+  const title = getPageOption("title", DEFAULT_OPTIONS) ?? options.title
+  const meta = { ...options.meta, ...getPageOption("meta", DEFAULT_OPTIONS) }
+  const styles = [
+    ...(options.styles ?? []),
+    ...getPageOption("styles", DEFAULT_OPTIONS),
+  ]
+  const head = getPageOption("head", DEFAULT_OPTIONS) ?? options.head
+  const scripts = [
+    ...(options.scripts ?? []),
+    ...getPageOption("scripts", DEFAULT_OPTIONS),
+  ]
+
+  return toHTML(store, (api) => api.render(moduleName, { allowType: true }), {
+    ...options,
+    lang,
+    charset,
+    title,
+    meta,
+    styles,
+    head,
+    scripts,
+  })
+}

package/src/render/layout.js

@@ -0,0 +1,37 @@
+export function layout(body, options) {
+  const {
+    lang = "en",
+    charset = "UTF-8",
+    title = "",
+    meta = {},
+    styles = [],
+    head = "",
+    scripts = [],
+    isDev,
+  } = options
+
+  return `<!DOCTYPE html>
+    <html lang="${lang}">
+      <head>
+        <meta charset="${charset}" />
+        <title>${title}</title>
+        ${Object.entries(meta)
+          .map(
+            ([name, content]) => `<meta name="${name}" content="${content}">`,
+          )
+          .join("\n")}
+        ${styles
+          .map((href) => `<link rel="stylesheet" href="${href}">`)
+          .join("\n")}
+        ${head}
+      </head>
+      <body>
+        <div id="root">${body}</div>
+        ${isDev ? `<script type="module" src="/@vite/client"></script>` : ``}
+        <script type="module" src="/main.js"></script>
+        ${scripts
+          .map((src) => `<script type="module" src="${src}"></script>`)
+          .join("\n")}
+      </body>
+    </html>`
+}

package/src/render/render.test.js

@@ -0,0 +1,111 @@
+import path from "node:path"
+
+import { createStore } from "@inglorious/web"
+import { expect, it } from "vitest"
+
+import { renderPage } from "."
+
+const ROOT_DIR = path.join(__dirname, "..", "__fixtures__")
+const PAGES_DIR = path.join(ROOT_DIR, "pages")
+
+const DEFAULT_OPTIONS = { stripLitMarkers: true }
+
+it("should render a static page fragment", async () => {
+  const module = await import(path.resolve(path.join(PAGES_DIR, "index.js")))
+  const page = { path: "/", moduleName: "index", module }
+
+  const store = createStore({
+    types: { index: module.index },
+    updateMode: "manual",
+  })
+
+  const html = await renderPage(store, page, undefined, DEFAULT_OPTIONS)
+
+  expect(html).toMatchSnapshot()
+})
+
+it("should render a page with entity", async () => {
+  const module = await import(path.resolve(path.join(PAGES_DIR, "about.js")))
+  const page = { path: "/about", moduleName: "about", module }
+  const entity = { type: "about", name: "Us" }
+
+  const store = createStore({
+    types: { about: module.about },
+    entities: { about: entity },
+    updateMode: "manual",
+  })
+
+  const html = await renderPage(store, page, entity, DEFAULT_OPTIONS)
+
+  expect(html).toMatchSnapshot()
+})
+
+it("should render a page with metadata", async () => {
+  const module = await import(path.resolve(path.join(PAGES_DIR, "about.js")))
+  const page = { path: "/about", moduleName: "about", module }
+  const entity = { type: "about", name: "Us" }
+
+  const store = createStore({
+    types: { about: module.about },
+    entities: { about: entity },
+    updateMode: "manual",
+  })
+
+  const html = await renderPage(store, page, module, {
+    ...DEFAULT_OPTIONS,
+    wrap: true,
+  })
+
+  expect(html).toMatchSnapshot()
+})
+
+it("should render a page with pre-fetched data", async () => {
+  const module = await import(path.resolve(path.join(PAGES_DIR, "blog.js")))
+  const page = { path: "/blog", moduleName: "blog", module }
+  const entity = {
+    type: "blog",
+    name: "Antony",
+    posts: [
+      { id: 1, title: "First Post" },
+      { id: 2, title: "Second Post" },
+      { id: 3, title: "Third Post" },
+    ],
+  }
+
+  const store = createStore({
+    types: { blog: module.blog },
+    entities: { blog: entity },
+    updateMode: "manual",
+  })
+
+  const html = await renderPage(store, page, module, DEFAULT_OPTIONS)
+
+  expect(html).toMatchSnapshot()
+})
+
+it("should render a dynamic page", async () => {
+  const module = await import(
+    path.resolve(path.join(PAGES_DIR, "posts/_slug.js"))
+  )
+  const page = { path: "/posts/1", moduleName: "post", module }
+  const entity = {
+    type: "blog",
+    name: "Antony",
+    post: {
+      id: 1,
+      title: "First Post",
+      date: "2026-01-04",
+      body: "Hello world!",
+    },
+  }
+
+  const store = createStore({
+    types: { blog: module.post },
+    entities: { post: entity },
+    updateMode: "manual",
+  })
+
+  const html = await renderPage(store, page, module, DEFAULT_OPTIONS)
+
+  expect(html).toMatchSnapshot()
+})

package/src/{router.js → router/index.js}

@@ -3,7 +3,7 @@ import { pathToFileURL } from "node:url"
 
 import { glob } from "glob"
 
-import { getModuleName } from "./module.js"
+import { getModuleName } from "../module.js"
 
 const NEXT_MATCH = 1
 
@@ -13,7 +13,6 @@ const SCORE_MULTIPLIER = 0.1
 
 /**
  * Get all static paths for SSG build.
- * This calls getStaticPaths() on dynamic route pages.
  */
 export async function getPages(pagesDir = "pages") {
   const routes = await getRoutes(pagesDir)
@@ -24,28 +23,30 @@ export async function getPages(pagesDir = "pages") {
     const moduleName = getModuleName(module)
 
     if (isDynamic(route.pattern)) {
-      // Dynamic route - call getStaticPaths if it exists
-      if (typeof module.getStaticPaths === "function") {
-        const paths = await module.getStaticPaths()
+      let { staticPaths = [] } = module
+      if (typeof staticPaths === "function") {
+        staticPaths = await staticPaths()
+      }
 
-        for (const pathOrObject of paths) {
-          const urlPath =
+      if (staticPaths.length) {
+        for (const pathOrObject of staticPaths) {
+          const path =
             typeof pathOrObject === "string" ? pathOrObject : pathOrObject.path
 
-          const params = extractParams(route, urlPath)
+          const params = extractParams(route, path)
 
           pages.push({
             pattern: route.pattern,
-            path: urlPath,
+            path,
+            params,
+            moduleName,
             modulePath: route.modulePath,
             filePath: route.filePath,
-            moduleName,
-            params,
           })
         }
       } else {
         console.warn(
-          `Dynamic route ${route.filePath} has no getStaticPaths export. ` +
+          `Dynamic route ${route.filePath} has no staticPaths export. ` +
             `It will be skipped during SSG.`,
         )
       }
@@ -54,10 +55,11 @@ export async function getPages(pagesDir = "pages") {
       pages.push({
         pattern: route.pattern,
         path: route.pattern || "/",
+        params: {},
+        module,
+        moduleName,
         modulePath: route.modulePath,
         filePath: route.filePath,
-        moduleName,
-        params: {},
       })
     }
   }

package/src/{router.test.js → router/router.test.js}

@@ -2,9 +2,9 @@ import path from "node:path"
 
 import { afterEach, describe, expect, it, vi } from "vitest"
 
-import { getPages, getRoutes, resolvePage } from "./router.js"
+import { getPages, getRoutes, resolvePage } from "./index.js"
 
-const ROOT_DIR = path.join(__dirname, "__fixtures__")
+const ROOT_DIR = path.join(__dirname, "..", "__fixtures__")
 const PAGES_DIR = path.join(ROOT_DIR, "pages")
 
 describe("router", () => {
@@ -25,8 +25,8 @@ describe("router", () => {
 
       const patterns = routes.map((r) => r.pattern)
 
-      expect(patterns).toContain("/posts/:id")
-      expect(patterns).toContain("/blog/:slug")
+      expect(patterns).toContain("/posts/:slug")
+      expect(patterns).toContain("/blog")
       expect(patterns).toContain("/about")
       expect(patterns).toContain("/")
       expect(patterns).toContain("/api/*")
@@ -39,7 +39,7 @@ describe("router", () => {
       // Root usually comes after specific paths but before catch-all if it was a catch-all root,
       // but here / is static.
       // Let's just check that we found them.
-      expect(routes).toHaveLength(6)
+      expect(routes).toHaveLength(5)
     })
   })
 
@@ -59,9 +59,9 @@ describe("router", () => {
     })
 
     it("should resolve dynamic page with params", async () => {
-      const page = await resolvePage("/blog/hello-world", PAGES_DIR)
+      const page = await resolvePage("/posts/hello-world", PAGES_DIR)
       expect(page).not.toBeNull()
-      expect(page.filePath).toContain("blog")
+      expect(page.filePath).toContain("posts")
       expect(page.params).toEqual({ slug: "hello-world" })
     })
 
@@ -93,12 +93,12 @@ describe("router", () => {
 
       expect(pages).toMatchSnapshot()
 
-      // Dynamic route without getStaticPaths should be skipped (and warn)
+      // Dynamic route without staticPaths should be skipped (and warn)
       const blogPage = pages.find((p) => p.path.includes("/blog/"))
       expect(blogPage).toBeUndefined()
 
       expect(consoleSpy).toHaveBeenCalled()
-      expect(consoleSpy.mock.calls[1][0]).toContain("has no getStaticPaths")
+      expect(consoleSpy.mock.calls[1][0]).toContain("has no staticPaths")
     })
   })
 })

package/src/scripts/app.js

@@ -1,5 +1,3 @@
-/* eslint-disable no-unused-vars */
-
 /**
  * Generate the code that goes inside the <!-- SSX --> marker.
  * This creates the types and entities objects for the client-side store.
@@ -18,7 +16,15 @@ export function generateApp(store, pages) {
   return `import { createDevtools, createStore, mount } from "@inglorious/web"
 import { getRoute, router, setRoutes } from "@inglorious/web/router"
 
-const pages = ${JSON.stringify(pages.map(({ filePath, ...page }) => page))}
+const pages = ${JSON.stringify(
+    pages.map(({ pattern, path, moduleName }) => ({
+      pattern,
+      path,
+      moduleName,
+    })),
+    null,
+    2,
+  )}
 const path = window.location.pathname + window.location.search + window.location.hash
 const page = pages.find((page) => page.path === path)
 

package/src/scripts/app.test.js

@@ -9,6 +9,7 @@ const ROOT_DIR = path.join(__dirname, "..", "__fixtures__")
 
 it("should generate the app script for a static page", async () => {
   const page = {
+    pattern: "/",
     path: "/",
     modulePath: "index.js",
     filePath: path.join(ROOT_DIR, "pages", "index.js"),
@@ -22,6 +23,7 @@ it("should generate the app script for a static page", async () => {
 
 it("should generate the app script for a page with an entity", async () => {
   const page = {
+    pattern: "/about",
     path: "/about",
     modulePath: "about.js",
     filePath: path.join(ROOT_DIR, "pages", "about.js"),
@@ -35,9 +37,24 @@ it("should generate the app script for a page with an entity", async () => {
 
 it("should generate the app script for a page that has metadata", async () => {
   const page = {
-    path: "/posts",
-    modulePath: "posts.js",
-    filePath: path.join(ROOT_DIR, "pages", "posts.js"),
+    pattern: "/blog",
+    path: "/blog",
+    modulePath: "blog.js",
+    filePath: path.join(ROOT_DIR, "pages", "blog.js"),
+  }
+  const store = await generateStore([page], { rootDir: ROOT_DIR })
+
+  const app = generateApp(store, [page])
+
+  expect(app).toMatchSnapshot()
+})
+
+it("should generate the app script for a dynamic page", async () => {
+  const page = {
+    pattern: "/posts/:slug",
+    path: "/posts/my-first-post",
+    modulePath: "post.js",
+    filePath: path.join(ROOT_DIR, "pages", "posts", "_slug.js"),
   }
   const store = await generateStore([page], { rootDir: ROOT_DIR })