@inglorious/ssx 1.0.0 → 1.1.1

package/src/build/public.test.js

@@ -0,0 +1,59 @@
+import fs from "node:fs/promises"
+import path from "node:path"
+
+import { afterEach, describe, expect, it, vi } from "vitest"
+
+import { copyPublicDir } from "./public"
+
+vi.mock("node:fs/promises")
+
+describe("copyPublicDir", () => {
+  const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {})
+
+  afterEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it("should copy public assets when directory exists", async () => {
+    // Mock access to succeed
+    fs.access.mockResolvedValue(undefined)
+
+    // Mock readdir sequence:
+    // 1. Root directory contains 'favicon.ico' (file) and 'assets' (dir)
+    // 2. 'assets' directory contains 'logo.png' (file)
+    fs.readdir
+      .mockResolvedValueOnce([
+        { name: "favicon.ico", isDirectory: () => false },
+        { name: "assets", isDirectory: () => true },
+      ])
+      .mockResolvedValueOnce([{ name: "logo.png", isDirectory: () => false }])
+
+    await copyPublicDir({ outDir: "dist", publicDir: "public" })
+
+    // Verify mkdir calls (root dest + subfolder)
+    expect(fs.mkdir).toHaveBeenCalledTimes(2)
+    expect(fs.mkdir).toHaveBeenCalledWith("dist", { recursive: true })
+    expect(fs.mkdir).toHaveBeenCalledWith(expect.stringContaining("assets"), {
+      recursive: true,
+    })
+
+    // Verify copyFile calls
+    expect(fs.copyFile).toHaveBeenCalledTimes(2)
+    // We can't easily check exact paths without mocking process.cwd() or doing complex string matching,
+    // but we can check that it was called for the files we defined.
+    const copyCalls = fs.copyFile.mock.calls
+    const filesCopied = copyCalls.map((call) => path.basename(call[0]))
+    expect(filesCopied).toContain("favicon.ico")
+    expect(filesCopied).toContain("logo.png")
+  })
+
+  it("should do nothing if public directory does not exist", async () => {
+    fs.access.mockRejectedValue(new Error("ENOENT"))
+
+    await copyPublicDir()
+
+    expect(consoleSpy).not.toHaveBeenCalled()
+    expect(fs.readdir).not.toHaveBeenCalled()
+    expect(fs.copyFile).not.toHaveBeenCalled()
+  })
+})

package/src/build/rss.js

@@ -0,0 +1,121 @@
+import fs from "node:fs/promises"
+import path from "node:path"
+
+/**
+ * Generates an RSS feed for the site.
+ *
+ * @param {Array<Object>} pages - Array of page objects. Each page must have a `metadata` property.
+ * @param {Object} options - RSS generation options.
+ * @param {string} [options.outDir="dist"] - Output directory.
+ * @param {string} [options.title="RSS Feed"] - Feed title.
+ * @param {string} [options.description="Latest Posts"] - Feed description.
+ * @param {string} options.link - Site URL (required).
+ * @param {string} [options.feedPath="/feed.xml"] - Path for the RSS file.
+ * @param {string} [options.language="en"] - Feed language.
+ * @param {string} [options.copyright] - Copyright notice.
+ * @param {number} [options.maxItems=50] - Maximum items to include.
+ * @param {Function} [options.filter] - Function to filter pages.
+ * @returns {Promise<void>}
+ */
+export async function generateRSS(pages = [], options = {}) {
+  const {
+    outDir = "dist",
+    title = "RSS Feed",
+    description = "Latest Posts",
+    link = "",
+    feedPath = "/feed.xml",
+    language = "en",
+    copyright = "",
+    maxItems = 50,
+    filter = () => true,
+  } = options
+
+  if (!link) {
+    console.warn("⚠️  No link provided for RSS feed, skipping...")
+    return
+  }
+
+  const items = pages
+    .filter(filter)
+    .map(({ metadata }) => metadata)
+    .sort(byNewest)
+    .slice(0, maxItems)
+
+  const rssItems = items.map(createRenderItem(link))
+
+  const xml = `<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
+  <channel>
+    <title>${escapeXml(title)}</title>
+    <link>${escapeXml(link)}</link>
+    <description>${escapeXml(description)}</description>
+    <language>${language}</language>
+    ${copyright ? `<copyright>${escapeXml(copyright)}</copyright>` : ""}
+    <lastBuildDate>${new Date().toUTCString()}</lastBuildDate>
+    <atom:link href="${escapeXml(link + feedPath)}" rel="self" type="application/rss+xml" />
+${rssItems.join("\n")}
+  </channel>
+</rss>`
+
+  const feedFilePath = path.join(outDir, feedPath.replace(/^\//, ""))
+  await fs.mkdir(path.dirname(feedFilePath), { recursive: true })
+  await fs.writeFile(feedFilePath, xml, "utf-8")
+
+  console.log(`  ✓ ${feedPath} (${items.length} items)\n`)
+}
+
+/**
+ * Creates a function to render a single RSS item.
+ *
+ * @param {string} link - The base URL of the site.
+ * @returns {Function} A function that takes metadata and returns an XML string.
+ */
+function createRenderItem(link) {
+  return (metadata) => {
+    const pubDate =
+      metadata.pubDate || metadata.date
+        ? new Date(metadata.pubDate || metadata.date).toUTCString()
+        : new Date().toUTCString()
+
+    const guid = metadata.guid || `${link}${metadata.path}`
+
+    return `    <item>
+      <title>${escapeXml(metadata.title)}</title>
+      <link>${escapeXml(link + metadata.path)}</link>
+      <guid>${escapeXml(guid)}</guid>
+      <pubDate>${pubDate}</pubDate>
+      ${metadata.description ? `<description>${escapeXml(metadata.description)}</description>` : ""}
+      ${metadata.author ? `<author>${escapeXml(metadata.author)}</author>` : ""}
+      ${metadata.category ? `<category>${escapeXml(metadata.category)}</category>` : ""}
+    </item>`
+  }
+}
+
+/**
+ * Escape special XML characters.
+ *
+ * @param {string} str - The string to escape.
+ * @returns {string} The escaped string.
+ */
+function escapeXml(str) {
+  if (typeof str !== "string") return str
+  return str
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;")
+}
+
+/**
+ * Sorts items by date (newest first).
+ *
+ * @param {Object} a - First item.
+ * @param {Object} b - Second item.
+ * @returns {number} Sort order.
+ */
+function byNewest(a, b) {
+  const dateA = new Date(a.pubDate || a.date || 0)
+  const dateB = new Date(b.pubDate || b.date || 0)
+  return dateB - dateA
+}

package/src/build/rss.test.js

@@ -0,0 +1,104 @@
+import fs from "node:fs/promises"
+
+import { afterEach, describe, expect, it, vi } from "vitest"
+
+import { generateRSS } from "./rss"
+
+vi.mock("node:fs/promises")
+
+describe("generateRSS", () => {
+  const consoleSpy = vi.spyOn(console, "warn").mockImplementation(() => {})
+  vi.spyOn(console, "log").mockImplementation(() => {})
+
+  afterEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it("should generate valid RSS xml", async () => {
+    const pages = [
+      {
+        metadata: {
+          title: "Post 1",
+          path: "/post-1",
+          date: "2024-01-01",
+          description: "Desc 1",
+        },
+      },
+    ]
+
+    await generateRSS(pages, {
+      link: "https://example.com",
+      title: "My Blog",
+    })
+
+    expect(fs.writeFile).toHaveBeenCalledTimes(1)
+    const [filePath, content] = fs.writeFile.mock.calls[0]
+
+    expect(filePath).toContain("feed.xml")
+    expect(content).toContain('<?xml version="1.0" encoding="UTF-8"?>')
+    expect(content).toContain('<rss version="2.0"')
+    expect(content).toContain("<title>My Blog</title>")
+    expect(content).toContain("<link>https://example.com</link>")
+    expect(content).toContain("<item>")
+    expect(content).toContain("<title>Post 1</title>")
+    expect(content).toContain("<link>https://example.com/post-1</link>")
+    expect(content).toContain("<pubDate>Mon, 01 Jan 2024")
+  })
+
+  it("should warn and skip if link is missing", async () => {
+    await generateRSS([], {})
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining("No link provided"),
+    )
+    expect(fs.writeFile).not.toHaveBeenCalled()
+  })
+
+  it("should sort items by newest date", async () => {
+    const pages = [
+      { metadata: { title: "Old", date: "2023-01-01" } },
+      { metadata: { title: "New", date: "2024-01-01" } },
+    ]
+
+    await generateRSS(pages, { link: "https://site.com" })
+
+    const [, content] = fs.writeFile.mock.calls[0]
+    const oldIndex = content.indexOf("<title>Old</title>")
+    const newIndex = content.indexOf("<title>New</title>")
+
+    expect(newIndex).toBeLessThan(oldIndex)
+  })
+
+  it("should respect maxItems option", async () => {
+    const pages = Array.from({ length: 10 }, (_, i) => ({
+      metadata: { title: `Post ${i}`, date: `2024-01-${i + 1}` },
+    }))
+
+    await generateRSS(pages, { link: "https://site.com", maxItems: 5 })
+
+    const [, content] = fs.writeFile.mock.calls[0]
+    const matches = content.match(/<item>/g)
+    expect(matches).toHaveLength(5)
+  })
+
+  it("should filter pages", async () => {
+    const pages = [
+      { path: "/blog/1", metadata: { title: "Blog 1" } },
+      { path: "/about", metadata: { title: "About" } },
+    ]
+
+    const filter = (page) => page.path.startsWith("/blog")
+
+    await generateRSS(pages, { link: "https://site.com", filter })
+
+    const [, content] = fs.writeFile.mock.calls[0]
+    expect(content).toContain("Blog 1")
+    expect(content).not.toContain("About")
+  })
+
+  it("should escape special characters", async () => {
+    const pages = [{ metadata: { title: "Q&A <Test>" } }]
+    await generateRSS(pages, { link: "https://site.com" })
+    const [, content] = fs.writeFile.mock.calls[0]
+    expect(content).toContain("Q&amp;A &lt;Test&gt;")
+  })
+})

package/src/build/sitemap.js

@@ -0,0 +1,66 @@
+import fs from "node:fs/promises"
+import path from "node:path"
+
+/**
+ * Generates a sitemap.xml file for the built site.
+ *
+ * @param {Array<Object>} pages - Array of page objects. Each page must have a `metadata` property.
+ * @param {Object} options - Sitemap generation options.
+ * @param {string} [options.outDir="dist"] - Output directory.
+ * @param {string} options.hostname - Base URL of the site (e.g., "https://mysite.com").
+ * @param {Function} [options.filter] - Function to filter pages before generation.
+ * @returns {Promise<void>}
+ */
+export async function generateSitemap(pages = [], options = {}) {
+  const { outDir = "dist", hostname = "", filter = () => true } = options
+
+  if (!hostname) {
+    console.warn("⚠️  No hostname provided for sitemap, skipping...")
+    return
+  }
+
+  const items = pages.filter(filter).map(({ metadata }) => metadata)
+
+  // Build XML
+  const urls = items.map(renderItem)
+
+  const xml = `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${urls.join("\n")}
+</urlset>`
+
+  const sitemapPath = path.join(outDir, "sitemap.xml")
+  await fs.writeFile(sitemapPath, xml, "utf-8")
+
+  console.log(`  ✓ sitemap.xml (${items.length} pages)\n`)
+}
+
+/**
+ * Renders a single URL entry for the sitemap.
+ *
+ * @param {Object} metadata - Page metadata (loc, lastmod, changefreq, priority).
+ * @returns {string} The XML string for the url element.
+ */
+function renderItem(metadata) {
+  return `  <url>
+    <loc>${escapeXml(metadata.loc)}</loc>
+    <lastmod>${metadata.lastmod}</lastmod>
+    <changefreq>${metadata.changefreq}</changefreq>
+    <priority>${metadata.priority}</priority>
+  </url>`
+}
+
+/**
+ * Escape special XML characters
+ *
+ * @param {string} str - The string to escape.
+ * @returns {string} The escaped string.
+ */
+function escapeXml(str) {
+  return str
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;")
+}

package/src/build/sitemap.test.js

@@ -0,0 +1,84 @@
+import fs from "node:fs/promises"
+
+import { afterEach, describe, expect, it, vi } from "vitest"
+
+import { generateSitemap } from "./sitemap"
+
+vi.mock("node:fs/promises")
+
+describe("generateSitemap", () => {
+  const consoleSpy = vi.spyOn(console, "warn").mockImplementation(() => {})
+  vi.spyOn(console, "log").mockImplementation(() => {})
+
+  afterEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it("should generate valid sitemap xml", async () => {
+    const pages = [
+      {
+        metadata: {
+          loc: "https://example.com/",
+          lastmod: "2024-01-01",
+          changefreq: "daily",
+          priority: 1.0,
+        },
+      },
+      {
+        metadata: {
+          loc: "https://example.com/about",
+          lastmod: "2024-01-02",
+          changefreq: "monthly",
+          priority: 0.8,
+        },
+      },
+    ]
+
+    await generateSitemap(pages, { hostname: "https://example.com" })
+
+    expect(fs.writeFile).toHaveBeenCalledTimes(1)
+    const [filePath, content] = fs.writeFile.mock.calls[0]
+
+    expect(filePath).toContain("sitemap.xml")
+    expect(content).toContain('<?xml version="1.0" encoding="UTF-8"?>')
+    expect(content).toContain(
+      '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+    )
+    expect(content).toContain("<loc>https://example.com/</loc>")
+    expect(content).toContain("<priority>1</priority>")
+    expect(content).toContain("<loc>https://example.com/about</loc>")
+    expect(content).toContain("<changefreq>monthly</changefreq>")
+  })
+
+  it("should warn and skip if hostname is missing", async () => {
+    await generateSitemap([], {})
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining("No hostname"),
+    )
+    expect(fs.writeFile).not.toHaveBeenCalled()
+  })
+
+  it("should filter pages based on filter function", async () => {
+    const pages = [
+      { path: "/public", metadata: { loc: "https://site.com/public" } },
+      { path: "/admin", metadata: { loc: "https://site.com/admin" } },
+    ]
+
+    const filter = (page) => page.path !== "/admin"
+
+    await generateSitemap(pages, { hostname: "https://site.com", filter })
+
+    const [, content] = fs.writeFile.mock.calls[0]
+    expect(content).toContain("/public")
+    expect(content).not.toContain("/admin")
+  })
+
+  it("should escape special characters in URLs", async () => {
+    const pages = [{ metadata: { loc: "https://site.com/foo?bar=1&baz=2" } }]
+
+    await generateSitemap(pages, { hostname: "https://site.com" })
+
+    const [, content] = fs.writeFile.mock.calls[0]
+    expect(content).toContain("foo?bar=1&amp;baz=2")
+  })
+})

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/dev/index.js

@@ -0,0 +1,98 @@
+import path from "node:path"
+
+import connect from "connect"
+import { createServer } from "vite"
+
+import { renderPage } from "../render/index.js"
+import { getPages, matchRoute } from "../router/index.js"
+import { generateApp } from "../scripts/app.js"
+import { generateStore } from "../store/index.js"
+import { loadConfig } from "../utils/config.js"
+import { createViteConfig, virtualFiles } from "./vite-config.js"
+
+/**
+ * Starts the development server.
+ * It sets up a Vite server with SSR middleware to render pages on demand.
+ *
+ * @param {Object} options - Configuration options.
+ * @returns {Promise<{close: Function}>} A promise that resolves to a server control object.
+ */
+export async function dev(options = {}) {
+  const config = await loadConfig(options)
+
+  const mergedOptions = { ...config, ...options }
+  const { rootDir = "src" } = mergedOptions
+
+  console.log("🚀 Starting dev server...\n")
+
+  // Get all pages once at startup
+  const pages = await getPages(path.join(rootDir, "pages"))
+  console.log(`📄 Found ${pages.length} pages\n`)
+
+  // Generate store config once for all pages
+  const store = await generateStore(pages, mergedOptions)
+
+  // Create Vite dev server
+  const viteConfig = createViteConfig(mergedOptions)
+  const viteServer = await createServer(viteConfig)
+
+  // Use Vite's middleware first (handles HMR, static files, etc.)
+  const connectServer = connect()
+
+  connectServer.use(viteServer.middlewares)
+
+  // Add SSR middleware
+  connectServer.use(async (req, res, next) => {
+    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)
+      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)
+      virtualFiles.set("/main.js", app)
+
+      res.setHeader("Content-Type", "text/html")
+      res.end(html)
+    } catch (error) {
+      viteServer.ssrFixStacktrace(error)
+      next(error) // Let Vite handle the error overlay
+    }
+  })
+
+  const { port = 3000 } = viteConfig.server ?? {}
+  const server = connectServer.listen(port)
+
+  console.log(`\n✨ Dev server running at http://localhost:${port}\n`)
+  console.log("Press Ctrl+C to stop\n")
+
+  return {
+    close: () => {
+      server.close()
+      viteServer.close()
+    },
+  }
+}

package/src/dev/vite-config.js

@@ -0,0 +1,60 @@
+import path from "node:path"
+
+import { mergeConfig } from "vite"
+
+/**
+ * Creates a Vite configuration object for the SSX dev server.
+ * It sets up the root directory, public directory, aliases, and the virtual file plugin.
+ *
+ * @param {Object} options - SSX configuration options.
+ * @param {string} [options.rootDir="src"] - The source root directory.
+ * @param {string} [options.publicDir="public"] - The public assets directory (relative to rootDir).
+ * @param {Object} [options.vite={}] - Additional Vite configuration to merge.
+ * @returns {Object} The merged Vite configuration.
+ */
+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,
+  )
+}
+
+/**
+ * A map to store virtual files generated during runtime (e.g., the client entry point).
+ * Keys are file paths (e.g., "/main.js") and values are the file content.
+ * @type {Map<string, string>}
+ */
+export const virtualFiles = new Map()
+
+/**
+ * A Vite plugin to serve virtual files from the `virtualFiles` map.
+ *
+ * @returns {Object} The Vite plugin object.
+ */
+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.test.js

@@ -0,0 +1,46 @@
+import path from "node:path"
+
+import { afterEach, describe, expect, it } from "vitest"
+
+import { createViteConfig, virtualFiles } from "./vite-config"
+
+describe("createViteConfig", () => {
+  it("should create default config", () => {
+    const config = createViteConfig()
+    expect(config.root).toBe(process.cwd())
+    expect(config.server.port).toBe(3000)
+    expect(config.resolve.alias["@"]).toBe(path.resolve(process.cwd(), "src"))
+  })
+
+  it("should respect custom rootDir", () => {
+    const config = createViteConfig({ rootDir: "app" })
+    expect(config.resolve.alias["@"]).toBe(path.resolve(process.cwd(), "app"))
+  })
+
+  it("should merge custom vite config", () => {
+    const config = createViteConfig({
+      vite: {
+        server: { port: 4000 },
+        define: { __TEST__: true },
+      },
+    })
+    expect(config.server.port).toBe(4000)
+    expect(config.define.__TEST__).toBe(true)
+  })
+})
+
+describe("virtualPlugin", () => {
+  afterEach(() => {
+    virtualFiles.clear()
+  })
+
+  it("should resolve and load virtual files", () => {
+    const config = createViteConfig()
+    const plugin = config.plugins.find((p) => p.name === "ssx-virtual-files")
+
+    virtualFiles.set("/virtual.js", "console.log('virtual')")
+
+    expect(plugin.resolveId("/virtual.js")).toBe("/virtual.js")
+    expect(plugin.load("/virtual.js")).toBe("console.log('virtual')")
+  })
+})