@inglorious/ssx 1.7.1 → 1.8.0

package/README.md

@@ -40,6 +40,7 @@ SSX takes your entity-based web apps and generates optimized static HTML with fu
 - **Optimized builds** - Minified, tree-shaken output
 - **Source maps** - Debug production like development
 - **Error boundaries** - Graceful failure handling
+- **Serverless functions** - API routes with Web Fetch API
 
 ---
 
@@ -128,11 +129,17 @@ npm run build
 # → Static site in dist/
 ```
 
-### Deploy
+### Preview
 
 ```bash
 npm run preview
-# → Preview production build
+# → Production server at http://localhost:3000 (serves static files + API routes)
+```
+
+Or use the CLI directly:
+
+```bash
+npx ssx serve
 ```
 
 Deploy `dist/` to:
@@ -486,6 +493,121 @@ title: My Post
 This is a markdown page.
 ```
 
+### ⚡ Serverless Functions (API Routes)
+
+SSX supports serverless functions for dynamic API endpoints. Create files in `src/api/` that export HTTP method handlers:
+
+```
+src/api/
+├── posts.js        → /api/posts
+├── posts/
+│   └── [id].js     → /api/posts/:id (alternative structure)
+└── users.js        → /api/users
+```
+
+#### Basic Example
+
+```javascript
+// src/api/posts.js
+export async function GET(request) {
+  const posts = [
+    { id: 1, title: "Hello World" },
+    { id: 2, title: "My Second Post" },
+  ]
+
+  return Response.json(posts)
+}
+
+export async function POST(request) {
+  const body = await request.json()
+  // Save to database...
+  return Response.json({ created: body }, { status: 201 })
+}
+```
+
+#### Dynamic Routes
+
+For routes like `/api/posts/:id`, export a single handler that parses the URL:
+
+```javascript
+// src/api/posts.js
+import { data } from "./posts-data.js"
+
+export async function GET(request) {
+  const url = new URL(request.url)
+  const segments = url.pathname.split("/").filter(Boolean)
+  const id = segments[1] // /api/posts/:id
+
+  if (id) {
+    const post = data.find((post) => post.id === id)
+    if (!post) {
+      return Response.json({ error: "Not found" }, { status: 404 })
+    }
+    return Response.json(post)
+  }
+
+  return Response.json(data)
+}
+```
+
+#### Using with Pages
+
+Fetch from your API in `routeChange` for client-side navigation, and use direct imports in `load` for build-time:
+
+```javascript
+// src/pages/posts/_slug.js
+import { html } from "@inglorious/web"
+
+export const post = {
+  async routeChange(entity, { route, params }, api) {
+    if (route !== entity.type) return
+
+    const entityId = entity.id
+    const response = await fetch(`/api/posts/${params.slug}`)
+    const post = await response.json()
+    post.body = renderMarkdown(post.body)
+    api.notify(`#${entityId}:dataFetchSuccess`, post)
+  },
+
+  dataFetchSuccess(entity, post) {
+    entity.post = post
+  },
+
+  render(entity) {
+    return html`<h1>${entity.post?.title}</h1>`
+  },
+}
+
+// Build-time: import directly (no HTTP overhead)
+export async function load(entity, page) {
+  const { data } = await import("../../api/posts.js")
+  entity.post = data.find((p) => p.id === page.params.slug)
+}
+```
+
+#### Request/Response API
+
+Handlers receive a standard Web `Request` object and should return a `Response`:
+
+```javascript
+export async function GET(request) {
+  // Access request properties
+  const url = new URL(request.url)
+  const search = url.searchParams.get("q")
+  const headers = request.headers.get("authorization")
+
+  // Return JSON response
+  return Response.json({ results: [] })
+
+  // Or custom response
+  return new Response("Not found", { status: 404 })
+}
+```
+
+#### Supported Methods
+
+Export any of these HTTP methods: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`.
+
 ---
 
 ## CLI
@@ -520,12 +642,18 @@ Options:
   -p, --port <port>    Dev server port (default: 3000)
 ```
 
-### `preview`
+### `ssx serve`
 
-Serves the built static site on port 3000 through the `serve` NPM package:
+Serves the production build with static files and API routes:
 
 ```bash
-pnpm preview
+pnpm ssx serve [options]
+
+Options:
+  -c, --config <file>  Config file (default: "site.config.js")
+  -r, --root <dir>     Source root directory (default: ".")
+  -o, --out <dir>      Output directory (default: "dist")
+  -p, --port <port>    Server port (default: 3000)
 ```
 
 ---
@@ -541,6 +669,8 @@ my-site/
 │   │   └── posts/
 │   │       ├── index.js    # /posts
 │   │       └── _id.js      # /posts/:id
+│   ├── api/            # Serverless functions
+│   │   └── posts.js    # /api/posts
 │   ├── store/          # Store configuration
 │   │   └── entities.js     # Entity definitions
 │   └── types/          # Custom entity types (optional)
@@ -737,6 +867,19 @@ await dev({
 })
 ```
 
+### Production Server API
+
+```javascript
+import { serve } from "@inglorious/ssx/serve"
+
+await serve({
+  rootDir: ".",
+  outDir: "dist",
+  port: 3000,
+  configFile: "site.config.js",
+})
+```
+
 ---
 
 <!-- ## Examples
@@ -756,7 +899,7 @@ Check out these example projects:
 - [x] Image optimization
 - [x] Markdown support
 - [x] i18n routing and locale-aware client navigation
-- [ ] API routes (serverless functions)
+- [x] API routes (serverless functions)
 
 ---
 

package/bin/ssx.js

@@ -8,6 +8,7 @@ import { Command } from "commander"
 
 import { build } from "../src/build/index.js"
 import { dev } from "../src/dev/index.js"
+import { serve } from "../src/serve/index.js"
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
@@ -87,6 +88,37 @@ program
     }
   })
 
+program
+  .command("serve")
+  .description("Serve production build with API routes")
+  .option("-c, --config <file>", "config file name", "site.config.js")
+  .option("-r, --root <dir>", "root directory", ".")
+  .option("-o, --out <dir>", "output directory", "dist")
+  .option("-p, --port <port>", "server port", 3000)
+  .action(async (options) => {
+    const cwd = process.cwd()
+    const rootDir = path.resolve(cwd, options.root)
+    const configPath = resolveConfigFile(rootDir, options.config)
+    const outDir = path.resolve(cwd, options.out)
+    const port = Number(options.port)
+
+    try {
+      await serve({
+        ...options,
+        config: undefined,
+        root: undefined,
+        out: undefined,
+        configPath,
+        rootDir,
+        outDir,
+        port,
+      })
+    } catch (error) {
+      console.error("Server failed:", error)
+      process.exit(1)
+    }
+  })
+
 program.parse()
 
 function resolveConfigFile(rootDir, configFile) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/ssx",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "description": "Server-Side-X. Xecution? Xperience? Who knows.",
   "author": "IceOnFire <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
   "license": "MIT",
@@ -27,6 +27,9 @@
   },
   "exports": {
     ".": "./types/index.d.ts",
+    "./dev": "./src/dev/index.js",
+    "./build": "./src/build/index.js",
+    "./serve": "./src/serve/index.js",
     "./markdown": "./src/utils/markdown.js",
     "./i18n": {
       "types": "./types/i18n.d.ts",
@@ -65,7 +68,6 @@
   },
   "devDependencies": {
     "prettier": "^3.6.2",
-    "serve": "^14.2.1",
     "vitest": "^1.6.1",
     "@inglorious/eslint-config": "1.1.2"
   },
@@ -79,6 +81,6 @@
     "test": "vitest run",
     "dev": "node ./bin/ssx.js dev -r ./src/__fixtures__",
     "build": "node ./bin/ssx.js build -r ./src/__fixtures__",
-    "preview": "serve dist"
+    "preview": "node ./bin/ssx.js serve -r ./src/__fixtures__"
   }
 }

package/src/dev/api.js

@@ -0,0 +1,77 @@
+import { existsSync } from "node:fs"
+import path from "node:path"
+
+export const createApiMiddleware = (rootDir, loader, onError) => {
+  return async (req, res, next) => {
+    const [urlPath] = req.url.split("?")
+
+    if (!urlPath.startsWith("/api/")) return next()
+
+    try {
+      const apiPath = urlPath.replace("/api/", "")
+      const segments = apiPath.split("/")
+      const searchPaths = []
+
+      for (let i = segments.length; i > 0; i--) {
+        searchPaths.push(segments.slice(0, i).join("/"))
+      }
+
+      let module = null
+
+      for (const searchPath of searchPaths) {
+        const apiFile = path.join(rootDir, "src", "api", `${searchPath}.js`)
+        if (existsSync(apiFile)) {
+          module = await loader(apiFile)
+          break
+        }
+      }
+
+      if (!module) {
+        res.statusCode = 404
+        res.setHeader("Content-Type", "application/json")
+        res.end(JSON.stringify({ error: "Not found" }))
+        return
+      }
+
+      const method = req.method.toUpperCase()
+
+      if (!module[method]) {
+        res.statusCode = 405
+        res.setHeader("Content-Type", "application/json")
+        res.end(JSON.stringify({ error: `Method ${method} not allowed` }))
+        return
+      }
+
+      const request = createRequest(req)
+      const response = await module[method](request)
+
+      await sendResponse(res, response)
+    } catch (error) {
+      onError?.(error)
+      next(error)
+    }
+  }
+}
+
+function createRequest(req) {
+  const protocol = req.socket.encrypted ? "https" : "http"
+  const host = req.headers.host || "localhost"
+  const url = `${protocol}://${host}${req.url}`
+
+  return new Request(url, {
+    method: req.method,
+    headers: req.headers,
+    body: req.method !== "GET" && req.method !== "HEAD" ? req : undefined,
+  })
+}
+
+async function sendResponse(res, response) {
+  res.statusCode = response.status
+
+  for (const [key, value] of response.headers) {
+    res.setHeader(key, value)
+  }
+
+  const body = await response.text()
+  res.end(body)
+}

package/src/dev/index.js

@@ -8,6 +8,7 @@ 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 { createApiMiddleware } from "./api.js"
 import { createViteConfig, virtualFiles } from "./vite-config.js"
 
 /**
@@ -36,6 +37,11 @@ export async function dev(options = {}) {
   const connectServer = connect()
   connectServer.use(viteServer.middlewares)
 
+  const apiMiddleware = createApiMiddleware(rootDir, loader, (error) =>
+    viteServer.ssrFixStacktrace(error),
+  )
+  connectServer.use(apiMiddleware)
+
   // Add SSR middleware
   connectServer.use(async (req, res, next) => {
     const [url] = req.url.split("?")
@@ -44,6 +50,7 @@ export async function dev(options = {}) {
       // Skip special routes, static files, AND public assets
       if (
         url.startsWith("/@") ||
+        url.startsWith("/api/") ||
         url.includes(".") || // Vite handles static files
         url === "/favicon.ico"
       ) {
@@ -73,7 +80,7 @@ export async function dev(options = {}) {
       }
 
       // Generate and update the virtual app file BEFORE rendering
-      const app = generateApp(store, pages, { ...mergedOptions, isDev: true })
+      const app = generateApp(pages, { ...mergedOptions, isDev: true })
       virtualFiles.set("/main.js", app)
 
       // Invalidate the virtual module to ensure Vite picks up changes

package/src/serve/index.js

@@ -0,0 +1,120 @@
+import { existsSync } from "node:fs"
+import { stat } from "node:fs/promises"
+import http from "node:http"
+import { createRequire } from "node:module"
+import path from "node:path"
+import { pathToFileURL } from "node:url"
+
+import connect from "connect"
+
+import { createApiMiddleware } from "../dev/api.js"
+import { loadConfig } from "../utils/config.js"
+
+const require = createRequire(import.meta.url)
+
+/**
+ * Starts a production server that serves static files and API routes.
+ *
+ * @param {Object} options - Configuration options.
+ * @returns {Promise<{close: Function}>} A promise that resolves to a server control object.
+ */
+export async function serve(options = {}) {
+  const config = await loadConfig(options)
+
+  const mergedOptions = { ...config, ...options }
+  const { rootDir = ".", outDir = "dist" } = mergedOptions
+
+  const { port = 3000 } = mergedOptions.vite?.server ?? {}
+
+  console.log("🚀 Starting production server...\n")
+
+  const connectServer = connect()
+
+  const distPath = path.resolve(process.cwd(), outDir)
+  const srcPath = path.resolve(process.cwd(), rootDir, "src")
+
+  const hasApi = existsSync(path.join(srcPath, "api"))
+  if (hasApi) {
+    const loader = (p) => import(pathToFileURL(p))
+    const apiMiddleware = createApiMiddleware(rootDir, loader)
+    connectServer.use(apiMiddleware)
+  }
+
+  connectServer.use(serveStatic(distPath))
+
+  const server = http.createServer(connectServer)
+
+  await new Promise((resolve) => server.listen(port, resolve))
+
+  console.log(`\n✨ Production server running at http://localhost:${port}\n`)
+  console.log(`📁 Serving from: ${distPath}\n`)
+  if (hasApi) {
+    console.log(`⚡ API routes enabled from: ${path.join(srcPath, "api")}\n`)
+  }
+  console.log("Press Ctrl+C to stop\n")
+
+  return {
+    close: () => server.close(),
+  }
+}
+
+function serveStatic(root) {
+  return async (req, res, next) => {
+    const [urlPath] = req.url.split("?")
+
+    let filePath = path.join(root, urlPath)
+
+    if (urlPath === "/" || urlPath === "") {
+      filePath = path.join(root, "index.html")
+    } else if (urlPath.endsWith("/")) {
+      filePath = path.join(root, urlPath, "index.html")
+    } else {
+      const stats = await stat(filePath).catch(() => null)
+      if (stats?.isDirectory()) {
+        filePath = path.join(filePath, "index.html")
+      }
+    }
+
+    if (!existsSync(filePath)) {
+      return next()
+    }
+
+    const ext = path.extname(filePath)
+    const contentType = getContentType(ext)
+
+    res.setHeader("Content-Type", contentType)
+
+    try {
+      const content = require("fs").readFileSync(filePath)
+      res.end(content)
+    } catch {
+      next()
+    }
+  }
+}
+
+function getContentType(ext) {
+  const types = {
+    ".html": "text/html",
+    ".css": "text/css",
+    ".js": "application/javascript",
+    ".mjs": "application/javascript",
+    ".json": "application/json",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".svg": "image/svg+xml",
+    ".ico": "image/x-icon",
+    ".webp": "image/webp",
+    ".avif": "image/avif",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+    ".ttf": "font/ttf",
+    ".eot": "application/vnd.ms-fontobject",
+    ".xml": "application/xml",
+    ".txt": "text/plain",
+  }
+
+  return types[ext] || "application/octet-stream"
+}