@inglorious/ssx 1.1.0 → 1.2.0

package/README.md

@@ -30,7 +30,7 @@ SSX takes your entity-based web apps and generates optimized static HTML with fu
 - **Hot reload dev server** - See changes instantly
 - **Lazy-loaded routes** - Code splitting automatically
 - **lit-html hydration** - Interactive UI without the bloat
-- **TypeScript ready** - Full type support (coming soon)
+- **TypeScript Ready** - Write your pages and entities in TypeScript.
 
 ### 🚀 Production Ready
 
@@ -59,6 +59,32 @@ npm run dev
 
 Or manually: -->
 
+### Create Your First Site (TypeScript)
+
+```typescript
+// src/pages/index.ts
+import { html } from "@inglorious/web"
+
+// You can import API for type safety, though it's optional
+// import type { API } from "@inglorious/web"
+
+export const index = {
+  render(/* entity: any, api: API */) {
+    return html`
+      <div>
+        <h1>Welcome to SSX!</h1>
+        <p>This page was pre-rendered at build time.</p>
+        <nav>
+          <a href="/about">About</a>
+        </nav>
+      </div>
+    `
+  },
+}
+```
+
+### Create Your First Site (JavaScript)
+
 ```javascript
 // src/pages/index.js
 import { html } from "@inglorious/web"
@@ -119,7 +145,7 @@ Deploy `dist/` to:
 
 ## Features
 
-### �️ Sitemap & RSS Generation
+### 🗺️ Sitemap & RSS Generation
 
 SSX automatically generates `sitemap.xml` and `rss.xml` based on your pages. Configure them in `src/site.config.js`:
 
@@ -159,7 +185,7 @@ export default {
 
 Pages with a `published` date in metadata are included in RSS feeds.
 
-### �📁 File-Based Routing
+### 📁 File-Based Routing
 
 Your file structure defines your routes:
 
@@ -609,7 +635,7 @@ Check out these example projects:
 
 ## Roadmap
 
-- [ ] TypeScript support
+- [x] TypeScript support
 - [ ] Image optimization
 - [ ] API routes (serverless functions)
 - [ ] MDX support

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/ssx",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Server-Side-X. Xecution? Xperience? Who knows.",
   "author": "IceOnFire <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
   "license": "MIT",
@@ -25,6 +25,9 @@
   "bin": {
     "ssx": "./bin/ssx.js"
   },
+  "exports": {
+    "./site.config": "./types/site.config.d.ts"
+  },
   "files": [
     "bin",
     "src",

package/src/build/build.test.js

@@ -1,11 +1,131 @@
+import fs from "node:fs/promises"
 import path from "node:path"
 
-import { it } from "vitest"
+import { build as viteBuild, createServer } from "vite"
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
 
+import { getPages } from "../router/index.js"
+import { generateApp } from "../scripts/app.js"
+import { generateStore } from "../store/index.js"
+import { loadConfig } from "../utils/config.js"
 import { build } from "."
+import {
+  createManifest,
+  determineRebuildPages,
+  hashEntities,
+  loadManifest,
+  saveManifest,
+} from "./manifest.js"
+import { generatePages } from "./pages.js"
+import { copyPublicDir } from "./public.js"
+import { generateRSS } from "./rss.js"
+import { generateSitemap } from "./sitemap.js"
+import { createViteConfig } from "./vite-config.js"
 
-const ROOT_DIR = path.join(__dirname, "__fixtures__")
+vi.mock("node:fs/promises")
+vi.mock("vite")
+vi.mock("../router/index.js")
+vi.mock("../scripts/app.js")
+vi.mock("../store/index.js")
+vi.mock("../utils/config.js")
+vi.mock("./manifest.js")
+vi.mock("./pages.js")
+vi.mock("./public.js")
+vi.mock("./rss.js")
+vi.mock("./sitemap.js")
+vi.mock("./vite-config.js")
 
-it.skip("should build full static pages", async () => {
-  await build({ rootDir: ROOT_DIR })
+describe("build", () => {
+  // Mock console to keep output clean
+  vi.spyOn(console, "log").mockImplementation(() => {})
+
+  beforeEach(() => {
+    createServer.mockResolvedValue({
+      ssrLoadModule: vi.fn(),
+      close: vi.fn(),
+    })
+  })
+
+  afterEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it("should run a full build sequence", async () => {
+    // Setup mocks
+    loadConfig.mockResolvedValue({})
+    loadManifest.mockResolvedValue(null) // First build
+    getPages.mockResolvedValue([{ path: "/" }])
+    hashEntities.mockResolvedValue("hash")
+    generateStore.mockResolvedValue({})
+    generatePages
+      .mockResolvedValueOnce([{ path: "/", html: "<html></html>" }])
+      .mockResolvedValueOnce([])
+    generateApp.mockReturnValue("console.log('app')")
+    createViteConfig.mockReturnValue({})
+    createManifest.mockResolvedValue({})
+
+    const result = await build({ rootDir: "src", outDir: "dist" })
+
+    // Verify sequence
+    expect(fs.rm).toHaveBeenCalledWith("dist", { recursive: true, force: true })
+    expect(fs.mkdir).toHaveBeenCalledWith("dist", { recursive: true })
+    expect(copyPublicDir).toHaveBeenCalled()
+    expect(getPages).toHaveBeenCalled()
+    expect(generateStore).toHaveBeenCalled()
+    expect(generatePages).toHaveBeenCalledTimes(2) // Changed + Skipped (empty)
+    expect(fs.writeFile).toHaveBeenCalledWith(
+      path.normalize("dist/index.html"),
+      "<html></html>",
+      "utf-8",
+    )
+    expect(generateApp).toHaveBeenCalled()
+    expect(viteBuild).toHaveBeenCalled()
+    expect(saveManifest).toHaveBeenCalled()
+
+    expect(result).toEqual({ changed: 1, skipped: 0 })
+  })
+
+  it("should handle incremental builds", async () => {
+    const manifest = { entities: "hash" }
+    loadManifest.mockResolvedValue(manifest)
+    hashEntities.mockResolvedValue("hash")
+
+    const allPages = [{ path: "/changed" }, { path: "/skipped" }]
+    getPages.mockResolvedValue(allPages)
+
+    determineRebuildPages.mockResolvedValue({
+      pagesToBuild: [{ path: "/changed" }],
+      pagesToSkip: [{ path: "/skipped" }],
+    })
+
+    generatePages
+      .mockResolvedValueOnce([{ path: "/changed", html: "<html></html>" }]) // Changed
+      .mockResolvedValueOnce([{ path: "/skipped" }]) // Skipped
+
+    const result = await build({ incremental: true })
+
+    expect(determineRebuildPages).toHaveBeenCalled()
+    expect(generatePages).toHaveBeenCalledTimes(2)
+    // Should only write changed pages
+    expect(fs.writeFile).toHaveBeenCalledWith(
+      expect.stringContaining("changed"),
+      expect.any(String),
+      expect.any(String),
+    )
+    expect(result).toEqual({ changed: 1, skipped: 1 })
+  })
+
+  it("should generate sitemap and rss if configured", async () => {
+    loadConfig.mockResolvedValue({})
+    getPages.mockResolvedValue([])
+    generatePages.mockResolvedValue([])
+
+    await build({
+      sitemap: { hostname: "https://example.com" },
+      rss: { link: "https://example.com" },
+    })
+
+    expect(generateSitemap).toHaveBeenCalled()
+    expect(generateRSS).toHaveBeenCalled()
+  })
 })

package/src/build/index.js

@@ -1,12 +1,12 @@
 import fs from "node:fs/promises"
 import path from "node:path"
 
-import { build as viteBuild } from "vite"
+import { build as viteBuild, createServer } from "vite"
 
-import { loadConfig } from "../config.js"
 import { getPages } from "../router/index.js"
 import { generateApp } from "../scripts/app.js"
-import { generateStore } from "../store.js"
+import { generateStore } from "../store/index.js"
+import { loadConfig } from "../utils/config.js"
 import {
   createManifest,
   determineRebuildPages,
@@ -20,6 +20,18 @@ import { generateRSS } from "./rss.js"
 import { generateSitemap } from "./sitemap.js"
 import { createViteConfig } from "./vite-config.js"
 
+/**
+ * Orchestrates the full static site build process.
+ *
+ * @param {Object} options - Build options.
+ * @param {string} [options.rootDir="src"] - Source directory.
+ * @param {string} [options.outDir="dist"] - Output directory.
+ * @param {boolean} [options.incremental=true] - Whether to use incremental builds.
+ * @param {boolean} [options.clean=false] - Whether to clean the output directory before building.
+ * @param {Object} [options.sitemap] - Sitemap configuration.
+ * @param {Object} [options.rss] - RSS configuration.
+ * @returns {Promise<{changed: number, skipped: number}>} Build statistics.
+ */
 export async function build(options = {}) {
   const config = await loadConfig(options)
 
@@ -35,6 +47,18 @@ export async function build(options = {}) {
 
   console.log("🔨 Starting build...\n")
 
+  // Create a temporary Vite server to load modules (supports TS)
+  const vite = await createServer({
+    ...createViteConfig(mergedOptions),
+    server: { middlewareMode: true, hmr: false },
+    appType: "custom",
+  })
+  const loader = (p) => vite.ssrLoadModule(p)
+
+  // 0. Get all pages to build (Fail fast if source is broken)
+  const allPages = await getPages(path.join(rootDir, "pages"), loader)
+  console.log(`📄 Found ${allPages.length} pages\n`)
+
   // Load previous build manifest
   const manifest = incremental && !clean ? await loadManifest(outDir) : null
 
@@ -51,32 +75,33 @@ export async function build(options = {}) {
   // 2. Copy public assets before generating pages (could be useful if need to read `public/data.json`)
   await copyPublicDir(options)
 
-  // 3. Get all pages to build
-  const allPages = await getPages(path.join(rootDir, "pages"))
-  console.log(`📄 Found ${allPages.length}\n`)
-
   // Determine which pages need rebuilding
   const entitiesHash = await hashEntities(rootDir)
-  let pagesToBuild = allPages
+  let pagesToChange = allPages
   let pagesToSkip = []
 
   if (manifest) {
     const result = await determineRebuildPages(allPages, manifest, entitiesHash)
-    pagesToBuild = result.pagesToBuild
+    pagesToChange = result.pagesToBuild
     pagesToSkip = result.pagesToSkip
 
     if (pagesToSkip.length) {
       console.log(
-        `⚡ Incremental build: ${pagesToBuild.length} to change, ${pagesToSkip.length} to skip\n`,
+        `⚡ Incremental build: ${pagesToChange.length} to change, ${pagesToSkip.length} to skip\n`,
       )
     }
   }
 
   // 4. Generate store with all types and initial entities
-  const store = await generateStore(allPages, mergedOptions)
+  const store = await generateStore(allPages, mergedOptions, loader)
 
   // 5. Render only pages that changed
-  const generatedPages = await generatePages(store, pagesToBuild, mergedOptions)
+  const changedPages = await generatePages(
+    store,
+    pagesToChange,
+    mergedOptions,
+    loader,
+  )
   // For skipped pages, load their metadata from disk if needed for sitemap/RSS
   const skippedPages = await generatePages(store, pagesToSkip, {
     ...mergedOptions,
@@ -84,47 +109,48 @@ export async function build(options = {}) {
   })
 
   // Combine rendered and skipped pages for sitemap/RSS
-  const allGeneratedPages = [...generatedPages, ...skippedPages]
+  const allGeneratedPages = [...changedPages, ...skippedPages]
 
-  if (generatedPages.length) {
+  if (changedPages.length) {
     // 6. Generate client-side JavaScript
     console.log("\n💾 Writing files...\n")
 
     // 7. Write HTML pages
-    for (const page of generatedPages) {
+    for (const page of changedPages) {
       const filePath = await writePageToDisk(page.path, page.html, outDir)
       console.log(`  ✓ ${filePath}`)
     }
   }
 
-  // Always regenerate client-side JavaScript (it's cheap and ensures consistency)
+  // 8. Always regenerate client-side JavaScript (it's cheap and ensures consistency)
   console.log("\n📝 Generating client scripts...\n")
 
   const app = generateApp(store, allPages)
   await fs.writeFile(path.join(outDir, "main.js"), app, "utf-8")
   console.log(`  ✓ main.js\n`)
 
-  // 7a. Generate sitemap if enabled
+  // 9. Generate sitemap if enabled
   if (sitemap?.hostname) {
     console.log("\n🗺️  Generating sitemap.xml...\n")
     await generateSitemap(allGeneratedPages, { outDir, ...sitemap })
   }
 
-  // 7b. Generate RSS feed if enabled
+  // 10. Generate RSS feed if enabled
   if (rss?.link) {
     console.log("\n📡 Generating RSS feed...\n")
     await generateRSS(allGeneratedPages, { outDir, ...rss })
   }
 
-  // 8. Bundle with Vite
+  // 11. Bundle with Vite
   console.log("\n📦 Bundling with Vite...\n")
   const viteConfig = createViteConfig(mergedOptions)
   await viteBuild(viteConfig)
 
-  // 9. Cleanup
+  await vite.close()
+  // 12. Cleanup
   // console.log("\n🧹 Cleaning up...\n")
 
-  // Save manifest for next build
+  // 13. Save manifest for next build
   if (incremental) {
     const newManifest = await createManifest(allGeneratedPages, entitiesHash)
     await saveManifest(outDir, newManifest)
@@ -133,13 +159,18 @@ export async function build(options = {}) {
   console.log("\n✨ Build complete!\n")
 
   return {
-    generated: generatedPages.length,
+    changed: changedPages.length,
     skipped: skippedPages.length,
   }
 }
 
 /**
  * Write a page to disk with proper directory structure.
+ *
+ * @param {string} pagePath - The URL path of the page.
+ * @param {string} html - The rendered HTML content.
+ * @param {string} [outDir="dist"] - The output directory.
+ * @returns {Promise<string>} The absolute path of the written file.
  */
 async function writePageToDisk(pagePath, html, outDir = "dist") {
   // Convert URL path to file path

package/src/build/manifest.js

@@ -6,8 +6,9 @@ const MANIFEST_FILE = ".ssx-manifest.json"
 
 /**
  * Loads the build manifest from the previous build.
- * @param {string} outDir - Output directory
- * @returns {Promise<Object>} The manifest object
+ *
+ * @param {string} outDir - Output directory.
+ * @returns {Promise<Object>} The manifest object.
  */
 export async function loadManifest(outDir) {
   const manifestPath = path.join(outDir, MANIFEST_FILE)
@@ -23,8 +24,10 @@ export async function loadManifest(outDir) {
 
 /**
  * Saves the build manifest for the next build.
- * @param {string} outDir - Output directory
- * @param {Object} manifest - The manifest to save
+ *
+ * @param {string} outDir - Output directory.
+ * @param {Object} manifest - The manifest to save.
+ * @returns {Promise<void>}
  */
 export async function saveManifest(outDir, manifest) {
   const manifestPath = path.join(outDir, MANIFEST_FILE)
@@ -34,8 +37,9 @@ export async function saveManifest(outDir, manifest) {
 
 /**
  * Computes a hash for a file's contents.
- * @param {string} filePath - Path to the file
- * @returns {Promise<string>} Hash of the file
+ *
+ * @param {string} filePath - Path to the file.
+ * @returns {Promise<string|null>} Hash of the file or null if not found.
  */
 export async function hashFile(filePath) {
   try {
@@ -48,8 +52,9 @@ export async function hashFile(filePath) {
 
 /**
  * Computes a hash for the entities file.
- * @param {string} rootDir - Source root directory
- * @returns {Promise<string>} Hash of entities.js
+ *
+ * @param {string} rootDir - Source root directory.
+ * @returns {Promise<string|null>} Hash of entities.js.
  */
 export async function hashEntities(rootDir) {
   const entitiesPath = path.join(rootDir, "entities.js")
@@ -58,10 +63,12 @@ export async function hashEntities(rootDir) {
 
 /**
  * Determines which pages need to be rebuilt.
- * @param {Array} pages - All pages to potentially build
- * @param {Object} manifest - Previous build manifest
- * @param {string} entitiesHash - Current entities hash
- * @returns {Promise<Object>} Object with pagesToBuild and pagesSkipped
+ * Compares current file hashes against the manifest.
+ *
+ * @param {Array<Object>} pages - All pages to potentially build.
+ * @param {Object} manifest - Previous build manifest.
+ * @param {string} entitiesHash - Current entities hash.
+ * @returns {Promise<{pagesToBuild: Array<Object>, pagesToSkip: Array<Object>}>} Object with pagesToBuild and pagesSkipped.
  */
 export async function determineRebuildPages(pages, manifest, entitiesHash) {
   // If entities changed, rebuild all pages
@@ -89,9 +96,10 @@ export async function determineRebuildPages(pages, manifest, entitiesHash) {
 
 /**
  * Creates a new manifest from build results.
- * @param {Array} renderedPages - All rendered pages
- * @param {string} entitiesHash - Hash of entities file
- * @returns {Object} New manifest
+ *
+ * @param {Array<Object>} renderedPages - All rendered pages.
+ * @param {string} entitiesHash - Hash of entities file.
+ * @returns {Promise<Object>} New manifest.
  */
 export async function createManifest(renderedPages, entitiesHash) {
   const pages = {}

package/src/build/manifest.test.js

@@ -0,0 +1,153 @@
+import fs from "node:fs/promises"
+
+import { afterEach, describe, expect, it, vi } from "vitest"
+
+import {
+  createManifest,
+  determineRebuildPages,
+  hashEntities,
+  hashFile,
+  loadManifest,
+  saveManifest,
+} from "./manifest"
+
+vi.mock("node:fs/promises")
+
+describe("manifest", () => {
+  const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {})
+
+  afterEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe("loadManifest", () => {
+    it("should load and parse manifest if exists", async () => {
+      const mockManifest = { pages: {}, entities: "abc" }
+      fs.readFile.mockResolvedValue(JSON.stringify(mockManifest))
+
+      const result = await loadManifest("dist")
+      expect(result).toEqual(mockManifest)
+      expect(fs.readFile).toHaveBeenCalledWith(
+        expect.stringContaining(".ssx-manifest.json"),
+        "utf-8",
+      )
+    })
+
+    it("should return default manifest if file missing", async () => {
+      fs.readFile.mockRejectedValue(new Error("ENOENT"))
+
+      const result = await loadManifest("dist")
+      expect(result).toEqual({ pages: {}, entities: null, buildTime: null })
+    })
+  })
+
+  describe("saveManifest", () => {
+    it("should write manifest to file", async () => {
+      const manifest = { pages: {} }
+      await saveManifest("dist", manifest)
+
+      expect(fs.writeFile).toHaveBeenCalledWith(
+        expect.stringContaining(".ssx-manifest.json"),
+        JSON.stringify(manifest, null, 2),
+        "utf-8",
+      )
+    })
+  })
+
+  describe("hashFile", () => {
+    it("should return md5 hash of file content", async () => {
+      fs.readFile.mockResolvedValue("content")
+      // md5("content") = 9a0364b9e99bb480dd25e1f0284c8555
+      const hash = await hashFile("file.txt")
+      expect(hash).toBe("9a0364b9e99bb480dd25e1f0284c8555")
+    })
+
+    it("should return null if file read fails", async () => {
+      fs.readFile.mockRejectedValue(new Error("ENOENT"))
+      const hash = await hashFile("file.txt")
+      expect(hash).toBeNull()
+    })
+  })
+
+  describe("hashEntities", () => {
+    it("should hash entities.js in root dir", async () => {
+      fs.readFile.mockResolvedValue("entities")
+      await hashEntities("src")
+      expect(fs.readFile).toHaveBeenCalledWith(
+        expect.stringContaining("entities.js"),
+        "utf-8",
+      )
+    })
+  })
+
+  describe("determineRebuildPages", () => {
+    it("should rebuild all if entities hash changed", async () => {
+      const pages = [{ path: "/" }]
+      const manifest = { entities: "old" }
+      const result = await determineRebuildPages(pages, manifest, "new")
+
+      expect(result.pagesToBuild).toEqual(pages)
+      expect(result.pagesToSkip).toEqual([])
+      expect(consoleSpy).toHaveBeenCalledWith(
+        expect.stringContaining("Entities changed"),
+      )
+    })
+
+    it("should split pages based on hash changes", async () => {
+      const pages = [
+        { path: "/changed", filePath: "changed.js" },
+        { path: "/same", filePath: "same.js" },
+      ]
+      const manifest = {
+        entities: "hash",
+        pages: {
+          "/changed": { hash: "old-hash" },
+          "/same": { hash: "9a0364b9e99bb480dd25e1f0284c8555" }, // md5("content")
+        },
+      }
+
+      // Mock hashFile behavior via fs.readFile
+      fs.readFile.mockImplementation(async (path) => {
+        if (path === "changed.js") return "new content"
+        if (path === "same.js") return "content"
+        return ""
+      })
+
+      const result = await determineRebuildPages(pages, manifest, "hash")
+
+      expect(result.pagesToBuild).toHaveLength(1)
+      expect(result.pagesToBuild[0].path).toBe("/changed")
+      expect(result.pagesToSkip).toHaveLength(1)
+      expect(result.pagesToSkip[0].path).toBe("/same")
+    })
+  })
+
+  describe("createManifest", () => {
+    it("should create a new manifest with page hashes", async () => {
+      const renderedPages = [
+        { path: "/", filePath: "index.js" },
+        { path: "/about", filePath: "about.js" },
+      ]
+      const entitiesHash = "entities-hash"
+
+      fs.readFile.mockImplementation(async (path) => {
+        if (path === "index.js") return "index content"
+        if (path === "about.js") return "about content"
+        return ""
+      })
+
+      const manifest = await createManifest(renderedPages, entitiesHash)
+
+      expect(manifest.entities).toBe(entitiesHash)
+      expect(manifest.buildTime).toBeDefined()
+      expect(manifest.pages["/"]).toEqual({
+        hash: "176b689259e8d68ef0aa869fd3b3be45",
+        filePath: "index.js",
+      })
+      expect(manifest.pages["/about"]).toEqual({
+        hash: "f43ab6cf4975e90e757c05cc3c619a85",
+        filePath: "about.js",
+      })
+    })
+  })
+})

package/src/build/metadata.js

@@ -1,4 +1,4 @@
-import { createGetPageOption } from "../page-options.js"
+import { createGetPageOption } from "../utils/page-options.js"
 
 const DEFAULT_OPTIONS = {
   title: "",

package/src/build/pages.js

@@ -4,8 +4,22 @@ import { pathToFileURL } from "node:url"
 import { renderPage } from "../render/index.js"
 import { extractPageMetadata } from "./metadata.js"
 
-export async function generatePages(store, pages, options = {}) {
+/**
+ * Generates HTML and metadata for a list of pages.
+ * It loads the page module, executes the `load` function (if defined),
+ * renders the HTML, and extracts metadata.
+ *
+ * @param {Object} store - The application store.
+ * @param {Array<Object>} pages - List of pages to generate.
+ * @param {Object} [options] - Generation options.
+ * @param {boolean} [options.shouldGenerateHtml=true] - Whether to generate HTML.
+ * @param {boolean} [options.shouldGenerateMetadata=true] - Whether to generate metadata.
+ * @param {Function} [loader] - Optional loader function.
+ * @returns {Promise<Array<Object>>} The processed pages with `html` and `metadata` properties added.
+ */
+export async function generatePages(store, pages, options = {}, loader) {
   const { shouldGenerateHtml = true, shouldGenerateMetadata = true } = options
+  const load = loader || ((p) => import(pathToFileURL(path.resolve(p))))
 
   const api = store._api
 
@@ -14,7 +28,7 @@ export async function generatePages(store, pages, options = {}) {
       `  Generating ${shouldGenerateHtml ? "HTML" : ""}${shouldGenerateHtml && shouldGenerateMetadata ? " and " : ""}${shouldGenerateMetadata ? "metadata" : ""} for ${page.path}...`,
     )
 
-    const module = await import(pathToFileURL(path.resolve(page.filePath)))
+    const module = await load(page.filePath)
     page.module = module
 
     const entity = api.getEntity(page.moduleName)