@wix/origami-site-express 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,18 @@
-# Temporary Holding Version
+# @wix/origami-site-express
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Runs an exported Wix origami site on Node with Express and Vite, on top of `@wix/origami-site`.
+Design: [docs/site-express-adapter-plan.md](../../../docs/site-express-adapter-plan.md).
+
+The site has no server code. Its scripts call the bin:
+
+| Script | Command | What it does |
+|---|---|---|
+| `yarn dev` | `origami-site-express dev` | Vite in middleware mode + Express + the core in dev mode: hot reload, live routing |
+
+`PORT` sets the port (default 3000). `yarn dev` listens on `localhost` only, because it serves the site's source
+through Vite; set `HOST=0.0.0.0` to reach it from another machine or a container. `VITE_WIX_CLIENT_ID` and `VITE_WIX_SITE_ID` come from `.env`.
+
+- The adapter loads `@wix/origami-site` from the **site root**, never its own copy.
+- In dev each request imports the core through Vite's module runner, so a linked core reloads on edit
+  without a restart. An installed core loads once.
+- HMR runs on the site's own port (`server.ws.server`).

package/bin/origami-site-express.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import * as commands from '../src/index.js'
+
+const [command] = process.argv.slice(2)
+if (!Object.hasOwn(commands, command)) {
+    console.error(`Usage: origami-site-express <${Object.keys(commands).join(' | ')}>`)
+    process.exit(1)
+}
+try {
+    await commands[command]({ root: process.cwd() })
+} catch (error) {
+    console.error(error instanceof Error ? error.stack ?? error.message : error)
+    process.exit(1)
+}

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@wix/origami-site-express",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Run an exported Wix origami site on Node with Express and Vite.",
+  "type": "module",
+  "files": [
+    "src",
+    "bin"
+  ],
+  "bin": {
+    "origami-site-express": "./bin/origami-site-express.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./adapter": {
+      "types": "./src/adapter/index.d.ts",
+      "default": "./src/adapter/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "scripts": {
+    "build": "tsc --noEmit",
+    "lint": "oxlint .",
+    "test": "node --test test/*.spec.js"
+  },
+  "dependencies": {
+    "@vitejs/plugin-react": "^6.1.1",
+    "express": "^5.2.1",
+    "vite": "^8.1.0"
+  },
+  "peerDependencies": {
+    "@wix/origami-site": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.0.0",
+    "@wix/origami-site": "0.1.0",
+    "typescript": "^6.0.3"
+  },
+  "publishUnscoped": false,
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "wix": {
+    "artifact": {
+      "groupId": "com.wixpress.npm",
+      "artifactId": "origami-site-express",
+      "targets": {
+        "docker": false
+      }
+    },
+    "validations": {
+      "source": [
+        "lint"
+      ],
+      "postBuild": [
+        "test"
+      ]
+    }
+  },
+  "falconPackageHash": "6b12967d51ce9c6f91010418e950985808b8bce67fc93f175fe38836"
 }

package/src/adapter/driver.js

@@ -0,0 +1,60 @@
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+
+const READY = /origami-site-express ready (\S+)/
+
+/** The bin of the adapter the site depends on, run with Node directly: the same command `yarn dev` runs. */
+const binPath = root => join(dirname(createRequire(join(root, 'package.json')).resolve('@wix/origami-site-express/package.json')), 'bin/origami-site-express.js')
+
+/** @param {'dev' | 'build' | 'start'} command @param {string} root @param {Record<string, string>} env */
+async function spawnBin(command, root, env) {
+    // Loaded here so the CLI can import the descriptor without child_process.
+    const { spawn } = await import('node:child_process')
+    const child = spawn(process.execPath, [binPath(root), command], {
+        cwd: root, stdio: ['ignore', 'pipe', 'pipe'],
+        env: { ...process.env, ...env, ...(command === 'start' ? { NODE_ENV: 'production' } : {}) },
+    })
+    let output = ''
+    child.stdout.on('data', chunk => { output += chunk })
+    child.stderr.on('data', chunk => { output += chunk })
+    /** @type {Promise<number | null>} */
+    const exited = new Promise(resolve => child.once('exit', code => resolve(code)))
+    return { child, exited, output: () => output }
+}
+
+/** @param {'dev' | 'start'} command @param {string} root @param {Record<string, string>} env @param {number} timeoutMs
+ * @returns {Promise<import('@wix/origami-site/types').RunningSite>} */
+async function run(command, root, env, timeoutMs) {
+    const { child, exited, output } = await spawnBin(command, root, env)
+    const url = await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => { child.kill('SIGKILL'); reject(new Error(`origami-site-express ${command} was not ready after ${timeoutMs} ms\n${output()}`)) }, timeoutMs)
+        const onData = () => {
+            const ready = READY.exec(output())
+            if (ready) { clearTimeout(timer); child.stdout.off('data', onData); resolve(new URL(ready[1])) }
+        }
+        child.stdout.on('data', onData)
+        exited.then(code => { clearTimeout(timer); reject(new Error(`origami-site-express ${command} exited with ${code}\n${output()}`)) })
+    })
+    return {
+        url,
+        logs: output,
+        restarts: () => output().split('\n').filter(line => line.includes('origami-site-express restarted')).length,
+        async stop() {
+            if (child.exitCode !== null || child.signalCode !== null) return
+            const kill = setTimeout(() => child.kill('SIGKILL'), 5_000)
+            child.kill('SIGTERM')
+            await exited
+            clearTimeout(kill)
+        },
+    }
+}
+
+/** @type {import('@wix/origami-site/types').ConformanceDriver} */
+export const driver = {
+    dev: (root, env) => run('dev', root, env, 30_000),
+    async build(root, env) {
+        const { exited, output } = await spawnBin('build', root, env)
+        return (await exited) === 0 ? { ok: true, output: output() } : { ok: false, output: output() }
+    },
+    start: (root, env) => run('start', root, env, 15_000),
+}

package/src/adapter/index.d.ts

@@ -0,0 +1,4 @@
+import type { OrigamiAdapter } from '@wix/origami-site/types'
+/** The adapter descriptor the CLI and the conformance suite load from `@wix/origami-site-express/adapter`. */
+declare const adapter: Omit<OrigamiAdapter, 'project'>
+export default adapter

package/src/adapter/index.js

@@ -0,0 +1,12 @@
+import { readFileSync } from 'node:fs'
+import { driver } from './driver.js'
+
+const pkg = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'))
+
+/** @type {Omit<import('@wix/origami-site/types').OrigamiAdapter, 'project'>} */
+export default {
+    name: pkg.name,
+    version: pkg.version,
+    framework: { name: 'express', range: pkg.dependencies.express },
+    conformance: driver,
+}

package/src/index.d.ts

@@ -0,0 +1,3 @@
+export type CommandOptions = { root: string }
+/** `origami-site-express dev`: Vite in middleware mode + Express + the core, live. */
+export function dev(options: CommandOptions): Promise<void>

package/src/index.js

@@ -0,0 +1 @@
+export { dev } from './server/dev.js'

package/src/server/bridge.js

@@ -0,0 +1,29 @@
+/** Express terminal middleware: Node req → Web Request → site.handle() → Web Response → Node res.
+ * @param {{
+ *   getSite: () => Promise<import('@wix/origami-site/types').OrigamiSite>,
+ *   renderPage: (resolution: Extract<import('@wix/origami-site/types').Resolution, { kind: 'page' }>, request: Request) => Promise<string>,
+ *   errorResponse: typeof import('@wix/origami-site/server').errorResponse,
+ *   node: typeof import('@wix/origami-site/node'),
+ *   mode: 'dev' | 'prod',
+ * }} options
+ * @returns {(req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse) => Promise<void>} */
+export function catchAll({ getSite, renderPage, errorResponse, node, mode }) {
+    return async (req, res) => {
+        const head = req.method === 'HEAD'
+        try {
+            const request = node.toWebRequest(req, res)
+            const resolution = await (await getSite()).handle(request)
+            let response
+            if (resolution.kind === 'page') {
+                const headers = new Headers(resolution.headers)
+                if (!headers.has('content-type')) headers.set('content-type', 'text/html; charset=utf-8')
+                response = new Response(await renderPage(resolution, request), { status: resolution.status, headers })
+            } else response = resolution.response
+            await node.sendWebResponse(res, response, { head })
+        } catch (error) {
+            // Part of the response is already out, or a failed body already closed it: a 500 can't follow.
+            if (res.headersSent || res.destroyed) res.destroy()
+            else await node.sendWebResponse(res, errorResponse(error, { mode }), { head })
+        }
+    }
+}

package/src/server/core.js

@@ -0,0 +1,16 @@
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+/** The site's own copy of the core, never this package's: under pnpm the two differ.
+ * @param {string} root @param {'server' | 'node' | 'build'} entry */
+export function coreEntry(root, entry) {
+    return createRequire(join(root, 'package.json')).resolve(`@wix/origami-site/${entry}`)
+}
+
+/** @param {string} root @returns {Promise<typeof import('@wix/origami-site/server')>} */
+export const importCoreServer = root => import(pathToFileURL(coreEntry(root, 'server')).href)
+/** @param {string} root @returns {Promise<typeof import('@wix/origami-site/node')>} */
+export const importCoreNode = root => import(pathToFileURL(coreEntry(root, 'node')).href)
+/** @param {string} root @returns {Promise<typeof import('@wix/origami-site/build')>} */
+export const importCoreBuild = root => import(pathToFileURL(coreEntry(root, 'build')).href)

package/src/server/currentSite.js

@@ -0,0 +1,49 @@
+/** @typedef {import('@wix/origami-site/types').OrigamiSite} OrigamiSite */
+/** @typedef {Awaited<ReturnType<OrigamiSite['table']>>} SiteRouteTable */
+
+/** The dev site, re-created whenever the core module is re-evaluated. `loadCore` imports the core through
+ * Vite's module runner: a linked core (outside node_modules) comes back as a new namespace object after an
+ * edit; an installed one loads once. A failed createSite is retried by the next request.
+ * @param {{ loadCore: () => Promise<any>, create: (core: any) => Promise<OrigamiSite> }} options
+ * @returns {{ currentSite: () => Promise<OrigamiSite>, site: () => OrigamiSite | undefined,
+ *   siteTree: { table: () => ReturnType<OrigamiSite['table']>, onTableChange: OrigamiSite['onTableChange'] } }} */
+export function createCurrentSite({ loadCore, create }) {
+    /** @type {{ core?: unknown, site?: OrigamiSite }} */
+    let current = {}
+    /** @type {{ core: unknown, site: Promise<OrigamiSite> } | undefined} */
+    let creating
+    /** @type {Set<(table: SiteRouteTable) => void>} */
+    const listeners = new Set()
+    /** @type {(() => void) | undefined} */
+    let unsubscribe
+    async function currentSite() {
+        const core = await loadCore()
+        if (core === current.core && current.site) return current.site
+        // A request that already sees a newer core waits for the older creation, then makes its own.
+        if (creating && creating.core !== core) { await creating.site.catch(() => {}); return currentSite() }
+        if (!creating) {
+            const site = (async () => {
+                await current.site?.close()
+                current = {}
+                const created = await create(core)
+                current = { core, site: created }
+                unsubscribe?.()
+                unsubscribe = created.onTableChange(table => { for (const listener of listeners) listener(table) })
+                return created
+            })().finally(() => { creating = undefined })
+            creating = { core, site }
+        }
+        return creating.site
+    }
+    return {
+        currentSite,
+        /** The site already created, if any: for watcher events, which must not create one. */
+        site: () => current.site,
+        /** What origamiVitePlugins reads. It was given once, at Vite startup, so it follows each new site. */
+        siteTree: {
+            table: async () => (await currentSite()).table(),
+            /** @param {(table: SiteRouteTable) => void} listener */
+            onTableChange(listener) { listeners.add(listener); return () => { listeners.delete(listener) } },
+        },
+    }
+}

package/src/server/dev.js

@@ -0,0 +1,51 @@
+import { createServer as createHttpServer } from 'node:http'
+import express from 'express'
+import { createServer as createViteServer, isRunnableDevEnvironment, loadEnv } from 'vite'
+import react from '@vitejs/plugin-react'
+import { coreEntry, importCoreBuild, importCoreNode, importCoreServer } from './core.js'
+import { catchAll } from './bridge.js'
+import { pageHtml } from './shell.js'
+import { host, port, siteOptions } from './env.js'
+import { serve } from './lifecycle.js'
+import { createCurrentSite } from './currentSite.js'
+
+/** `origami-site-express dev`: Vite in middleware mode, Express, and the core in dev mode, all live.
+ * @param {{ root: string }} options */
+export async function dev({ root }) {
+    const env = loadEnv('development', root, ['VITE_', 'ORIGAMI_'])
+    const { errorResponse, serializePageData } = await importCoreServer(root)
+    const { origamiVitePlugins } = await importCoreBuild(root)
+    const node = await importCoreNode(root)
+    const serverEntry = coreEntry(root, 'server')
+    const { currentSite, site, siteTree } = createCurrentSite({
+        loadCore: () => isRunnableDevEnvironment(vite.environments.ssr) ? vite.environments.ssr.runner.import(serverEntry) : vite.ssrLoadModule(serverEntry),
+        create: core => core.createSite({ root, mode: 'dev', ...siteOptions(env) }),
+    })
+    const httpServer = createHttpServer()
+    const vite = await createViteServer({
+        root, configFile: false, appType: 'custom', mode: 'development',
+        // HMR on the site's own port: without it Vite opens a second port, and two sites would collide.
+        server: { middlewareMode: true, ws: { server: httpServer } },
+        // React after ours: origami:jsx-checks is enforce 'pre', so our Babel checks see the source first.
+        plugins: [...origamiVitePlugins({ root, siteTree }), react()],
+        // No index.html lists the pages, so Vite can't scan them up front. Without this, the first visit to a lazily
+        // loaded page finds new dependencies, re-optimizes them and reloads, and the page briefly runs two Reacts.
+        optimizeDeps: { entries: ['src/site/_generated/client.jsx', 'src/pages/**/_generated/index.jsx'] },
+        // The core's CommonJS dependencies go to Node. Linked (as in this repo), Vite would inline them as ESM,
+        // where `exports` is not defined. Add any CommonJS package the core starts importing.
+        ssr: { external: ['@wix/origami-types'] },
+    })
+    vite.watcher.on('all', (_event, path) => site()?.fileChanged(path))
+    const app = express()
+    app.disable('x-powered-by')
+    app.use(vite.middlewares)
+    app.use(catchAll({
+        mode: 'dev', errorResponse, node, getSite: currentSite,
+        renderPage: (resolution, request) => vite.transformIndexHtml(new URL(request.url).pathname, pageHtml(resolution, {
+            serializePageData,
+            body: '<script type="module" src="/src/site/_generated/client.jsx"></script>',
+        })),
+    }))
+    httpServer.on('request', app)
+    await serve(httpServer, { port: port(), host: host('dev'), onClose: async () => { await vite.close(); await site()?.close() } })
+}

package/src/server/env.js

@@ -0,0 +1,15 @@
+/** The createSite options that come from the environment.
+ * @param {Record<string, string | undefined>} env */
+export function siteOptions(env) {
+    return {
+        wix: { clientId: env.VITE_WIX_CLIENT_ID ?? '', siteId: env.VITE_WIX_SITE_ID ?? '' },
+        ...(env.ORIGAMI_WIX_API_BASE ? { wixApiBaseUrl: env.ORIGAMI_WIX_API_BASE } : {}),
+    }
+}
+
+export const port = () => Number(process.env.PORT ?? 3000)
+
+/** Dev serves the site's source through Vite, so it stays on this machine unless HOST says otherwise.
+ * 127.0.0.1, not localhost: on macOS localhost binds only ::1. Start listens on every interface, for Docker.
+ * @param {'dev' | 'prod'} mode */
+export const host = mode => process.env.HOST || (mode === 'dev' ? '127.0.0.1' : undefined)

package/src/server/lifecycle.js

@@ -0,0 +1,24 @@
+/** Listens, prints the one ready line, and shuts down on SIGTERM/SIGINT. No host means every interface.
+ * @param {import('node:http').Server} server @param {{ port: number, host?: string | undefined, onClose: () => Promise<unknown> }} options */
+export async function serve(server, { port, host, onClose }) {
+    await new Promise((resolve, reject) => { server.once('error', reject); server.listen(port, host, () => resolve(undefined)) })
+    const address = /** @type {import('node:net').AddressInfo} */ (server.address())
+    // The URL a client can open: the bound address, or localhost when listening on every interface.
+    const shown = !host || address.address === '::' || address.address === '0.0.0.0' ? 'localhost'
+        : address.family === 'IPv6' ? `[${address.address}]` : address.address
+    console.log(`origami-site-express ready http://${shown}:${address.port}`)
+    let stopping = false
+    const stop = async () => {
+        if (stopping) return
+        stopping = true
+        const closed = new Promise(resolve => server.close(resolve))
+        server.closeIdleConnections()
+        const force = setTimeout(() => server.closeAllConnections(), 10_000).unref()
+        try { await onClose() } catch (error) { console.error('[origami]', error) }
+        await closed
+        clearTimeout(force)
+        process.exit(0)
+    }
+    process.once('SIGTERM', stop)
+    process.once('SIGINT', stop)
+}

package/src/server/shell.js

@@ -0,0 +1,23 @@
+const escapeHtml = value => String(value).replace(/[&<>"']/g, char => ({
+    '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
+})[char])
+
+/** The HTML shell for a page Resolution, the same in dev and prod; only the asset tags differ.
+ * @param {Extract<import('@wix/origami-site/types').Resolution, { kind: 'page' }>} resolution
+ * @param {{ serializePageData: (data: import('@wix/origami-site/types').PageData) => string, head?: string, body: string }} parts */
+export function pageHtml({ page, data }, { serializePageData, head = '', body }) {
+    return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>${escapeHtml(page.title)}</title>
+    ${head}
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="application/json" id="origami-page">${serializePageData(data)}</script>
+    ${body}
+  </body>
+</html>`
+}