npm - @inglorious/ssx - Versions diffs - 1.1.0 → 1.2.0 - Mend

@inglorious/ssx 1.1.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (38) hide show

package/README.md +30 -4
package/package.json +4 -1
package/src/build/build.test.js +124 -4
package/src/build/index.js +53 -22
package/src/build/manifest.js +23 -15
package/src/build/manifest.test.js +153 -0
package/src/build/metadata.js +1 -1
package/src/build/pages.js +16 -2
package/src/build/pages.test.js +83 -0
package/src/build/public.js +15 -0
package/src/build/public.test.js +59 -0
package/src/build/rss.js +30 -11
package/src/build/rss.test.js +104 -0
package/src/build/sitemap.js +15 -6
package/src/build/sitemap.test.js +84 -0
package/src/dev/index.js +18 -27
package/src/dev/vite-config.js +20 -0
package/src/dev/vite-config.test.js +46 -0
package/src/render/html.js +27 -1
package/src/render/index.js +11 -1
package/src/render/layout.js +15 -0
package/src/render/layout.test.js +58 -0
package/src/render/render.test.js +87 -84
package/src/router/index.js +118 -56
package/src/router/router.test.js +33 -2
package/src/scripts/app.js +6 -2
package/src/scripts/app.test.js +46 -44
package/src/store/index.js +44 -0
package/src/store/store.test.js +74 -0
package/src/{module.js → utils/module.js} +8 -0
package/src/utils/module.test.js +64 -0
package/src/utils/page-options.js +17 -0
package/src/utils/page-options.test.js +57 -0
package/src/module.test.js +0 -45
package/src/page-options.js +0 -8
package/src/store.js +0 -29
package/src/store.test.js +0 -40
/package/src/{config.js → utils/config.js} +0 -0

package/src/render/index.js CHANGED Viewed

@@ -1,4 +1,4 @@
-import { createGetPageOption } from "../page-options.js"
+import { createGetPageOption } from "../utils/page-options.js"
 import { toHTML } from "./html.js"
 const DEFAULT_OPTIONS = {
@@ -11,6 +11,16 @@ const DEFAULT_OPTIONS = {
   scripts: [],
 }
+/**
+ * Renders a specific page using the store and page options.
+ * It resolves page-specific metadata (title, meta, etc.) before rendering.
+ *
+ * @param {Object} store - The application store.
+ * @param {Object} page - The page object (from router).
+ * @param {Object} entity - The entity associated with the page.
+ * @param {Object} [options] - Global site options/defaults.
+ * @returns {Promise<string>} The rendered HTML.
+ */
 export async function renderPage(store, page, entity, options = {}) {
   const { moduleName, module } = page

package/src/render/layout.js CHANGED Viewed

@@ -1,3 +1,18 @@
+/**
+ * Default layout function for wrapping content in a full HTML document.
+ *
+ * @param {string} body - The body content HTML.
+ * @param {Object} options - Layout options.
+ * @param {string} [options.lang="en"] - Language attribute.
+ * @param {string} [options.charset="UTF-8"] - Character set.
+ * @param {string} [options.title=""] - Page title.
+ * @param {Object} [options.meta={}] - Meta tags.
+ * @param {string[]} [options.styles=[]] - Stylesheets.
+ * @param {string} [options.head=""] - Additional head content.
+ * @param {string[]} [options.scripts=[]] - Scripts.
+ * @param {boolean} [options.isDev] - Whether in dev mode.
+ * @returns {string} The full HTML document.
+ */
 export function layout(body, options) {
   const {
     lang = "en",

package/src/render/layout.test.js ADDED Viewed

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest"
+import { layout } from "./layout"
+describe("layout", () => {
+  it("should render default layout structure", () => {
+    const html = layout("<h1>Hello</h1>", {})
+    expect(html).toContain("<!DOCTYPE html>")
+    expect(html).toContain('<html lang="en">')
+    expect(html).toContain('<meta charset="UTF-8" />')
+    expect(html).toContain('<div id="root"><h1>Hello</h1></div>')
+    expect(html).toContain('<script type="module" src="/main.js"></script>')
+  })
+  it("should render with custom title and language", () => {
+    const html = layout("", { title: "My Page", lang: "fr" })
+    expect(html).toContain("<title>My Page</title>")
+    expect(html).toContain('<html lang="fr">')
+  })
+  it("should render meta tags", () => {
+    const html = layout("", {
+      meta: { description: "Desc", viewport: "width=device-width" },
+    })
+    expect(html).toContain('<meta name="description" content="Desc">')
+    expect(html).toContain(
+      '<meta name="viewport" content="width=device-width">',
+    )
+  })
+  it("should render styles", () => {
+    const html = layout("", { styles: ["/style.css", "/theme.css"] })
+    expect(html).toContain('<link rel="stylesheet" href="/style.css">')
+    expect(html).toContain('<link rel="stylesheet" href="/theme.css">')
+  })
+  it("should render scripts", () => {
+    const html = layout("", { scripts: ["/app.js"] })
+    expect(html).toContain('<script type="module" src="/app.js"></script>')
+  })
+  it("should render additional head content", () => {
+    const html = layout("", { head: '<link rel="icon" href="/favicon.ico">' })
+    expect(html).toContain('<link rel="icon" href="/favicon.ico">')
+  })
+  it("should include vite client in dev mode", () => {
+    const html = layout("", { isDev: true })
+    expect(html).toContain(
+      '<script type="module" src="/@vite/client"></script>',
+    )
+  })
+  it("should not include vite client in prod mode", () => {
+    const html = layout("", { isDev: false })
+    expect(html).not.toContain("/@vite/client")
+  })
+})

package/src/render/render.test.js CHANGED Viewed

@@ -1,111 +1,114 @@
 import path from "node:path"
+import { pathToFileURL } from "node:url"
 import { createStore } from "@inglorious/web"
-import { expect, it } from "vitest"
+import { describe, expect, it } from "vitest"
 import { renderPage } from "."
-const ROOT_DIR = path.join(__dirname, "..", "__fixtures__")
+const ROOT_DIR = path.join(import.meta.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 }
+describe("renderPage", () => {
+  it("should render a static page fragment", async () => {
+    const module = await import(pathToFileURL(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()
-})
+    const store = createStore({
+      types: { index: module.index },
+      updateMode: "manual",
+    })
-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 html = await renderPage(store, page, undefined, DEFAULT_OPTIONS)
-  const store = createStore({
-    types: { about: module.about },
-    entities: { about: entity },
-    updateMode: "manual",
+    expect(html).toMatchSnapshot()
   })
-  const html = await renderPage(store, page, entity, DEFAULT_OPTIONS)
+  it("should render a page with entity", async () => {
+    const module = await import(pathToFileURL(path.join(PAGES_DIR, "about.js")))
+    const page = { path: "/about", moduleName: "about", module }
+    const entity = { type: "about", name: "Us" }
-  expect(html).toMatchSnapshot()
-})
+    const store = createStore({
+      types: { about: module.about },
+      entities: { about: entity },
+      updateMode: "manual",
+    })
-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 html = await renderPage(store, page, entity, DEFAULT_OPTIONS)
-  const store = createStore({
-    types: { about: module.about },
-    entities: { about: entity },
-    updateMode: "manual",
+    expect(html).toMatchSnapshot()
   })
-  const html = await renderPage(store, page, module, {
-    ...DEFAULT_OPTIONS,
-    wrap: true,
-  })
+  it("should render a page with metadata", async () => {
+    const module = await import(pathToFileURL(path.join(PAGES_DIR, "about.js")))
+    const page = { path: "/about", moduleName: "about", module }
+    const entity = { type: "about", name: "Us" }
-  expect(html).toMatchSnapshot()
-})
+    const store = createStore({
+      types: { about: module.about },
+      entities: { about: entity },
+      updateMode: "manual",
+    })
-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()
-})
+    const html = await renderPage(store, page, module, {
+      ...DEFAULT_OPTIONS,
+      wrap: true,
+    })
-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",
+    expect(html).toMatchSnapshot()
   })
-  const html = await renderPage(store, page, module, DEFAULT_OPTIONS)
+  it("should render a page with pre-fetched data", async () => {
+    const module = await import(pathToFileURL(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()
+  })
-  expect(html).toMatchSnapshot()
+  it("should render a dynamic page", async () => {
+    const module = await import(
+      pathToFileURL(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/index.js CHANGED Viewed

@@ -3,7 +3,7 @@ import { pathToFileURL } from "node:url"
 import { glob } from "glob"
-import { getModuleName } from "../module.js"
+import { getModuleName } from "../utils/module.js"
 const NEXT_MATCH = 1
@@ -12,55 +12,69 @@ const CATCH_ALL_ROUTE_WEIGHT = -10
 const SCORE_MULTIPLIER = 0.1
 /**
- * Get all static paths for SSG build.
+ * Scans the pages directory and returns a list of all pages to be built.
+ * For dynamic routes, it calls the `staticPaths` export of the page module
+ * to generate all possible paths.
+ *
+ * @param {string} pagesDir - The directory containing page files.
+ * @param {Function} [loader] - Optional loader function (e.g. vite.ssrLoadModule).
+ * @returns {Promise<Array<Object>>} A list of page objects with metadata.
  */
-export async function getPages(pagesDir = "pages") {
+export async function getPages(pagesDir = "pages", loader) {
   const routes = await getRoutes(pagesDir)
   const pages = []
+  const load = loader || ((p) => import(pathToFileURL(path.resolve(p))))
   for (const route of routes) {
-    const module = await import(pathToFileURL(path.resolve(route.filePath)))
-    const moduleName = getModuleName(module)
-    if (isDynamic(route.pattern)) {
-      let { staticPaths = [] } = module
-      if (typeof staticPaths === "function") {
-        staticPaths = await staticPaths()
-      }
+    try {
+      const module = await load(route.filePath)
+      const moduleName = getModuleName(module)
+      if (isDynamic(route.pattern)) {
+        let { staticPaths = [] } = module
+        if (typeof staticPaths === "function") {
+          staticPaths = await staticPaths()
+        }
-      if (staticPaths.length) {
-        for (const pathOrObject of staticPaths) {
-          const path =
-            typeof pathOrObject === "string" ? pathOrObject : pathOrObject.path
-          const params = extractParams(route, path)
-          pages.push({
-            pattern: route.pattern,
-            path,
-            params,
-            moduleName,
-            modulePath: route.modulePath,
-            filePath: route.filePath,
-          })
+        if (staticPaths.length) {
+          for (const pathOrObject of staticPaths) {
+            const path =
+              typeof pathOrObject === "string"
+                ? pathOrObject
+                : pathOrObject.path
+            const params = extractParams(route, path)
+            pages.push({
+              pattern: route.pattern,
+              path,
+              params,
+              moduleName,
+              modulePath: route.modulePath,
+              filePath: route.filePath,
+            })
+          }
+        } else {
+          console.warn(
+            `Dynamic route ${route.filePath} has no staticPaths export. ` +
+              `It will be skipped during SSG.`,
+          )
         }
       } else {
-        console.warn(
-          `Dynamic route ${route.filePath} has no staticPaths export. ` +
-            `It will be skipped during SSG.`,
-        )
+        // Static route - add directly
+        pages.push({
+          pattern: route.pattern,
+          path: route.pattern || "/",
+          params: {},
+          module,
+          moduleName,
+          modulePath: route.modulePath,
+          filePath: route.filePath,
+        })
       }
-    } else {
-      // Static route - add directly
-      pages.push({
-        pattern: route.pattern,
-        path: route.pattern || "/",
-        params: {},
-        module,
-        moduleName,
-        modulePath: route.modulePath,
-        filePath: route.filePath,
-      })
+    } catch (error) {
+      console.error(`\n❌ Failed to load page: ${route.filePath}`)
+      throw error
     }
   }
@@ -68,8 +82,12 @@ export async function getPages(pagesDir = "pages") {
 }
 /**
- * Resolve a URL to a page file and extract params.
- * Used by dev server for on-demand rendering.
+ * Resolves a URL to a specific page file and extracts route parameters.
+ * This is primarily used by the development server for on-demand rendering.
+ *
+ * @param {string} url - The URL to resolve (e.g., "/posts/hello").
+ * @param {string} pagesDir - The directory containing page files.
+ * @returns {Promise<{filePath: string, params: Object}|null>} The resolved page info or null if not found.
  */
 export async function resolvePage(url, pagesDir = "pages") {
   const routes = await getRoutes(pagesDir)
@@ -98,12 +116,15 @@ export async function resolvePage(url, pagesDir = "pages") {
 }
 /**
- * Discovers all pages in the pages directory.
- * Returns an array of route objects with pattern matching info.
+ * Discovers all page files and converts them into route definitions.
+ * Routes are sorted by specificity so that more specific routes match first.
+ *
+ * @param {string} pagesDir - The directory containing page files.
+ * @returns {Promise<Array<Object>>} A list of route objects.
  */
 export async function getRoutes(pagesDir = "pages") {
   // Find all .js and .ts files in pages directory
-  const files = await glob("**/*.{js,ts}", {
+  const files = await glob("**/*.{js,ts,jsx,tsx}", {
     cwd: pagesDir,
     ignore: ["**/*.test.{js,ts}", "**/*.spec.{js,ts}"],
     posix: true,
@@ -134,16 +155,44 @@ export async function getRoutes(pagesDir = "pages") {
 }
 /**
- * Convert a file path to a route pattern.
- * pages/index.js -> /
- * pages/about.js -> /about
- * pages/blog/[slug].js -> /blog/:slug
- * pages/api/[...path].js -> /api/*
+ * Simple route matcher.
+ * Checks if a URL matches a route pattern (handling dynamic segments).
+ *
+ * @param {string} pattern - The route pattern (e.g. "/posts/:id").
+ * @param {string} url - The actual URL (e.g. "/posts/123").
+ * @returns {boolean} True if it matches.
+ */
+export function matchRoute(pattern, url) {
+  const patternParts = pattern.split("/").filter(Boolean)
+  const urlParts = url.split("/").filter(Boolean)
+  if (patternParts.length !== urlParts.length) {
+    return false
+  }
+  return patternParts.every((part, i) => {
+    if (part.startsWith(":") || part.startsWith("[")) {
+      return true
+    }
+    return part === urlParts[i]
+  })
+}
+/**
+ * Converts a file path to a route pattern.
+ * Examples:
+ * - pages/index.js -> /
+ * - pages/about.js -> /about
+ * - pages/blog/_slug.js -> /blog/:slug
+ * - pages/api/__path.js -> /api/*
+ *
+ * @param {string} file - The relative file path.
+ * @returns {string} The route pattern.
  */
 function filePathToPattern(file) {
   let pattern = file
     .replace(/\\/g, "/")
-    .replace(/\.(js|ts)$/, "") // Remove extension
+    .replace(/\.(js|ts|jsx|tsx)$/, "") // Remove extension
     .replace(/\/index$/, "") // index becomes root of directory
     .replace(/^index$/, "") // Handle root index
     .replace(/__(\w+)/g, "*") // __path becomes *
@@ -154,7 +203,10 @@ function filePathToPattern(file) {
 }
 /**
- * Convert a route pattern to a regex and extract parameter names.
+ * Converts a route pattern to a regex and extracts parameter names.
+ *
+ * @param {string} pattern - The route pattern.
+ * @returns {{regex: RegExp, params: string[]}} The regex and parameter names.
  */
 function patternToRegex(pattern) {
   const params = []
@@ -181,8 +233,11 @@ function patternToRegex(pattern) {
 }
 /**
- * Calculate route specificity for sorting.
+ * Calculates route specificity for sorting.
  * Higher score = more specific = should match first.
+ *
+ * @param {string} pattern - The route pattern.
+ * @returns {number} The specificity score.
  */
 function routeSpecificity(pattern) {
   let score = 0
@@ -211,14 +266,21 @@ function routeSpecificity(pattern) {
 }
 /**
- * Check if a pattern is dynamic (contains params or wildcards).
+ * Checks if a pattern is dynamic (contains params or wildcards).
+ *
+ * @param {string} pattern - The route pattern.
+ * @returns {boolean} True if dynamic.
  */
 function isDynamic(pattern) {
   return pattern.includes(":") || pattern.includes("*")
 }
 /**
- * Extract params from a URL based on a route.
+ * Extracts params from a URL based on a route.
+ *
+ * @param {Object} route - The route object.
+ * @param {string} url - The URL to match.
+ * @returns {Object} The extracted parameters.
  */
 function extractParams(route, url) {
   const match = route.regex.exec(url)

package/src/router/router.test.js CHANGED Viewed

@@ -2,9 +2,9 @@ import path from "node:path"
 import { afterEach, describe, expect, it, vi } from "vitest"
-import { getPages, getRoutes, resolvePage } from "./index.js"
+import { getPages, getRoutes, matchRoute, resolvePage } from "./index.js"
-const ROOT_DIR = path.join(__dirname, "..", "__fixtures__")
+const ROOT_DIR = path.join(import.meta.dirname, "..", "__fixtures__")
 const PAGES_DIR = path.join(ROOT_DIR, "pages")
 describe("router", () => {
@@ -84,6 +84,12 @@ describe("router", () => {
       const page = await resolvePage("/foo", PAGES_DIR)
       expect(page).toBeNull()
     })
+    it("should return null for dynamic route missing param", async () => {
+      // /posts/:slug requires a slug
+      const page = await resolvePage("/posts", PAGES_DIR)
+      expect(page).toBeNull()
+    })
   })
   describe("getPages", () => {
@@ -101,4 +107,29 @@ describe("router", () => {
       expect(consoleSpy.mock.calls[1][0]).toContain("has no staticPaths")
     })
   })
+  describe("matchRoute", () => {
+    it("should match static routes", () => {
+      expect(matchRoute("/", "/")).toBe(true)
+      expect(matchRoute("/about", "/about")).toBe(true)
+      expect(matchRoute("/about", "/contact")).toBe(false)
+    })
+    it("should match dynamic routes", () => {
+      expect(matchRoute("/posts/:id", "/posts/123")).toBe(true)
+      expect(matchRoute("/users/[id]", "/users/antony")).toBe(true)
+    })
+    it("should not match if segment length differs", () => {
+      expect(matchRoute("/", "/about")).toBe(false)
+      expect(matchRoute("/posts/:id", "/posts/123/comments")).toBe(false)
+      expect(matchRoute("/posts/:id", "/posts")).toBe(false)
+    })
+    it("should handle trailing slashes implicitly via split", () => {
+      // split('/').filter(Boolean) removes empty strings, so trailing slashes are ignored
+      expect(matchRoute("/about/", "/about")).toBe(true)
+      expect(matchRoute("/about", "/about/")).toBe(true)
+    })
+  })
 })

package/src/scripts/app.js CHANGED Viewed

@@ -1,6 +1,10 @@
 /**
- * Generate the code that goes inside the <!-- SSX --> marker.
- * This creates the types and entities objects for the client-side store.
+ * Generates the client-side entry point script.
+ * This script hydrates the store with the initial state (entities) and sets up the router.
+ *
+ * @param {Object} store - The server-side store instance containing the initial state.
+ * @param {Array<Object>} pages - List of page objects to generate routes for.
+ * @returns {string} The generated JavaScript code for the client entry point.
  */
 export function generateApp(store, pages) {
   // Collect all unique page modules and their exports