catalyst-core 0.3.0-beta.3 → 0.3.0-beta.4

package/dist/server/expressServer.js

@@ -10,6 +10,7 @@ import pc from "picocolors"
 import fs from "fs"
 const { cyan, yellow, green } = pc
 
+import { toMountPathPrefix } from "../vite/resolveDevServerConfig.js"
 import { validateMiddleware, safeCall } from "./utils/validator.js"
 import { botDetectionMiddleware } from "./utils/botDetectionMiddleware.js"
 import { cjsRequire } from "./utils/cjsRequire.js"
@@ -208,6 +209,12 @@ async function createServer() {
             appType: "custom",
             root: process.env.src_path,
         })
+
+        // Expose Vite's resolved base to the SSR renderer so the URLs it injects
+        // (client entry, react-refresh preamble) match the path Vite serves under.
+        // Vite normalizes base with a trailing slash; trim it for clean URL joins.
+        process.env.APP_MOUNT_PATH = toMountPathPrefix(vite.config.base)
+
         app.use(vite.middlewares)
     }
 

package/dist/server/renderer/document/Body.jsx

@@ -30,7 +30,10 @@ export function Body(props) {
                     __html: `window.__SAFE_AREA_INITIAL__ = ${JSON.stringify(safeArea)}; window.__CATALYST_NATIVE_WEBVIEW__ = ${nativeWebView ? "true" : "false"}`,
                 }}
             />
-            {process.env.NODE_ENV === "development" && <script type="module" src="/client/index.js"></script>}
+            {process.env.NODE_ENV === "development" && (
+                // Base pinned to Vite's resolved base by server/expressServer.js.
+                <script type="module" src={`${process.env.APP_MOUNT_PATH || ""}/client/index.js`}></script>
+            )}
             {jsx}
             <script
                 /* eslint-disable */

package/dist/vite/FastRefresh.jsx

@@ -6,8 +6,10 @@ const FastRefresh = () => {
             type="module"
             // eslint-disable-next-line risxss/catch-potential-xss-react
             dangerouslySetInnerHTML={{
+                // Base-prefixed so the preamble resolves under a sub-path; otherwise
+                // plugin-react modules throw "$RefreshSig$ is not defined".
                 __html: `
-        import { injectIntoGlobalHook } from "/@react-refresh";
+        import { injectIntoGlobalHook } from "${process.env.APP_MOUNT_PATH || ""}/@react-refresh";
         injectIntoGlobalHook(window);
         window.$RefreshReg$ = () => {};
         window.$RefreshSig$ = () => (type) => type;

package/dist/vite/loadCustomViteConfig.js

@@ -5,6 +5,34 @@ import { pathToFileURL } from "url"
 const emptyConfig = {
     ssrPlugins: [],
     clientPlugins: [],
+    /**
+     * devServer lets apps tune the Vite dev server without editing framework
+     * internals.  All fields are optional and map 1-to-1 onto Vite's `server`
+     * config (https://vite.dev/config/server-options).
+     *
+     * The most common use-case is an app served under a sub-path behind an SSL
+     * reverse proxy (nginx/caddy):
+     *
+     *   // buildConfig.js
+     *   export default {
+     *     devServer: {
+     *       // Vite's base path — the single source of truth for the dev mount
+     *       // path; must match the reverse-proxy location prefix. Defaults to "/".
+     *       base: "/o-mweb",
+     *
+     *       // HMR WebSocket tuning when the browser connects via the proxy
+     *       hmr: {
+     *         clientPort: 443,   // port the browser uses (proxy's SSL port)
+     *         path: "__vite_hmr" // WebSocket pathname (relative to base)
+     *       },
+     *
+     *       // Vite 6 rejects requests whose Host header isn't localhost/127.0.0.1.
+     *       // Add your proxy hostname here so the dev server accepts them.
+     *       allowedHosts: ["local.odinweb.1mg.com"],
+     *     },
+     *   }
+     */
+    devServer: {},
 }
 
 export async function loadCustomViteConfig() {

package/dist/vite/node-loader.mjs

@@ -308,9 +308,37 @@ function isValidExportName(name) {
 // Loader-scoped require for discovering CJS exports
 const loaderRequire = createRequire(import.meta.url)
 
-const CJS_PATTERN = /\b(module\.exports\b|exports\.\w+\s*=)/
 const REQUIRE_CALL_PATTERN = /\brequire\s*\(/
 
+/**
+ * Decide whether a source file is really CommonJS by parsing it, not by
+ * regex-matching the raw text.
+ *
+ * A regex like /module\.exports\b/ cannot tell code from text, so any file that
+ * merely *mentions* module.exports inside a string, comment or template literal
+ * was misclassified as CJS. When such a file was real ESM with its own
+ * `export default`, the CJS shim appended a second one and Node failed the
+ * module with "Duplicate export of 'default'". Docs sites hit this constantly:
+ * a Markdown page documenting a CJS config compiles into a string literal in
+ * the bundled ESM output. Do not reintroduce source-regex detection.
+ *
+ * esbuild parses properly and lowers CJS itself, so a file it wraps in its
+ * __commonJS helper had no ESM syntax of its own — that is the CJS signal.
+ */
+function isCjsSource(source, filePath) {
+    try {
+        const { code } = transformSync(source, {
+            loader: "jsx",
+            format: "esm",
+            sourcefile: filePath,
+            target: "node20",
+        })
+        return /\bvar __commonJS =/.test(code)
+    } catch {
+        return false
+    }
+}
+
 // Shim __dirname and __filename for ESM app files (these globals only exist in CJS)
 const createDirnameShim = (source) => {
     const hasFilename = /\b(?:const|let|var)\s+__filename\b/.test(source)
@@ -396,7 +424,7 @@ export async function load(url, context, defaultLoad) {
         // We can't use createRequire here because the file lives in a "type":"module"
         // package — Node's CJS require refuses to load it. Instead, we wrap the
         // source inline so that `module.exports` becomes the default export.
-        if (CJS_PATTERN.test(source)) {
+        if (isCjsSource(source, filePath)) {
             const shimmed = [
                 createRequireShim(source),
                 createDirnameShim(source),

package/dist/vite/resolveDevServerConfig.js

@@ -0,0 +1,45 @@
+// Pure resolvers for the Vite dev-server config derived from an app's
+// `buildConfig.devServer`. Side-effect free so the base precedence and the fs
+// allowlist merge can be unit-tested without spinning up Vite.
+
+/**
+ * Vite `base` for the dev server. `buildConfig.devServer.base` is the single
+ * source of truth (default "/"). Normalized to a leading slash and no trailing
+ * slash so it doubles as a URL prefix for the SSR renderer.
+ */
+export function resolveDevBase(devServer = {}) {
+    const base = devServer?.base
+    if (!base || base === "/") return "/"
+    return `/${String(base).trim().replace(/^\/+|\/+$/g, "")}`
+}
+
+/**
+ * A resolved base as a URL prefix. Root ("/") becomes "" so
+ * `${prefix}/client/index.js` stays single-slashed.
+ */
+export function toMountPathPrefix(base) {
+    return !base || base === "/" ? "" : String(base).replace(/\/+$/, "")
+}
+
+/**
+ * fs.allow for the dev server. Framework paths are always present; apps may
+ * extend the list via `devServer.fs.allow` but cannot replace it or relax other
+ * fs guards (e.g. `strict`), so buildConfig can't widen filesystem exposure.
+ */
+export function resolveDevFsAllow(devFs, frameworkPaths) {
+    const extra = Array.isArray(devFs?.allow) ? devFs.allow : []
+    return [...frameworkPaths, ...extra]
+}
+
+/**
+ * Vite `server` block from `buildConfig.devServer`. Passthrough keys are spread
+ * first so the framework-owned `hmr` and `fs` always win.
+ */
+export function buildDevServer(devServer = {}, { frameworkPaths, isProduction = false } = {}) {
+    const { base, hmr, fs, ...serverOverrides } = devServer
+    return {
+        ...serverOverrides,
+        hmr: isProduction ? false : (hmr ?? true),
+        fs: { allow: resolveDevFsAllow(fs, frameworkPaths) },
+    }
+}

package/dist/vite/vite.config.client.js

@@ -1,7 +1,7 @@
 import loadEnvironmentVariables from "../scripts/loadEnvironmentVariables.js"
 loadEnvironmentVariables()
 import { defineConfig } from "vite"
-import baseConfig, { getClientEnvVariables } from "./vite.config.js"
+import { sharedViteConfig as baseConfig, getClientEnvVariables } from "./vite.config.js"
 import path from "path"
 import { manifestCategorizationPlugin } from "./manifest-categorization-plugin.js"
 import { injectCacheKeyPlugin } from "./inject-cache-key-plugin.js"

package/dist/vite/vite.config.js

@@ -2,6 +2,8 @@ import { defineConfig, transformWithEsbuild } from "vite"
 import react from "@vitejs/plugin-react"
 import svgr from "vite-plugin-svgr"
 import { builtinModules, createRequire } from "node:module"
+import { loadCustomViteConfig } from "./loadCustomViteConfig.js"
+import { resolveDevBase, buildDevServer } from "./resolveDevServerConfig.js"
 
 /**
  * Treat all .scss imports as CSS modules (webpack compat).
@@ -362,7 +364,10 @@ export const isNodeOnlyExternal = (id) =>
     id === "@grpc/grpc-js" ||
     id.startsWith("@opentelemetry/")
 
-export default defineConfig({
+// ─── Shared config ────────────────────────────────────────────────────────────
+// Exported for the production build (vite.config.client.js spreads this in).
+// Does NOT include `base` or `server` — those differ between dev and prod.
+export const sharedViteConfig = {
     // Parallel `vite build` (SSR + client) must use separate dirs or Vite will block on shared `node_modules/.vite`.
     cacheDir: path.join(
         process.env.src_path,
@@ -488,17 +493,34 @@ export default defineConfig({
         "**/*.woff2",
     ],
 
-    // Server configuration
-    server: {
-        hmr: !isProduction,
-        fs: {
-            allow: [process.env.src_path, __dirname],
-        },
-    },
-
     // Preview configuration for production preview
     preview: {
         port: process.env.NODE_SERVER_PORT ? parseInt(process.env.NODE_SERVER_PORT) : 3005,
         host: process.env.NODE_SERVER_HOSTNAME || "localhost",
     },
+}
+
+// ─── Dev server config ────────────────────────────────────────────────────────
+// Async factory so it can read the app's buildConfig.devServer for `base`, HMR
+// and other Vite server options. `base` comes solely from devServer.base; the
+// resolved value is propagated to the SSR renderer by server/expressServer.js.
+// The production build (vite.config.client.js) ignores this and spreads
+// sharedViteConfig directly.
+export default defineConfig(async () => {
+    const { devServer = {}, ssrPlugins = [] } = await loadCustomViteConfig()
+
+    return {
+        ...sharedViteConfig,
+        base: resolveDevBase(devServer),
+        server: buildDevServer(devServer, {
+            frameworkPaths: [process.env.src_path, __dirname],
+            isProduction,
+        }),
+        // Apply the app's SSR plugins in dev too — the production build already
+        // does this in vite.config.server.js. This lets buildConfig.ssrPlugins
+        // inject SSR-only config (e.g. a plugin whose `config()` hook adds
+        // ssr.noExternal to bundle React-consuming deps so dev SSR shares the
+        // app's single React instance) without hardcoding anything in the framework.
+        plugins: [...(sharedViteConfig.plugins || []), ...ssrPlugins],
+    }
 })

package/dist/vite/vite.config.server.js

@@ -1,7 +1,11 @@
 import loadEnvironmentVariables from "../scripts/loadEnvironmentVariables.js"
 loadEnvironmentVariables()
 import { defineConfig } from "vite"
-import baseConfig, { getClientEnvVariables, isNodeOnlyExternal } from "./vite.config.js"
+// Spread the static shared config (a plain object), NOT the default export —
+// the default export is now an async dev-server factory function, and spreading
+// a function would silently drop cacheDir, resolve aliases, css, plugins and
+// build from the production SSR bundle. Mirrors vite.config.client.js.
+import { sharedViteConfig as baseConfig, getClientEnvVariables, isNodeOnlyExternal } from "./vite.config.js"
 import path from "path"
 import { fileURLToPath } from "url"
 import { dirname } from "path"

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "catalyst-core",
-    "version": "0.3.0-beta.3",
+    "version": "0.3.0-beta.4",
     "type": "module",
     "main": "./dist/index.jsx",
     "description": "Web framework that provides great performance out of the box",
@@ -30,6 +30,7 @@
     "scripts": {
         "lint": "eslint .",
         "lint-staged": "lint-staged",
+        "test:unit": "node --test \"test/**/*.test.js\"",
         "prettify": "prettier . --write",
         "prepare": "node ../../scripts/safe-rimraf.js ./dist && cp -r ./src ./dist && babel src/native --out-dir dist/native --config-file ./babel.native.config.cjs --ignore '**/.build/**' && babel src/sentry.js --out-file dist/sentry.cjs --config-file ./babel.native.config.cjs",
         "prepublishOnly": "npm run prepare",

package/test/vite/resolveDevServerConfig.test.js

@@ -0,0 +1,113 @@
+import { test } from "node:test"
+import assert from "node:assert/strict"
+
+import {
+    resolveDevBase,
+    toMountPathPrefix,
+    resolveDevFsAllow,
+    buildDevServer,
+} from "../../src/vite/resolveDevServerConfig.js"
+
+// ─── resolveDevBase ───────────────────────────────────────────────────────────
+
+test("resolveDevBase: resolves from devServer.base", () => {
+    assert.equal(resolveDevBase({ base: "/o-mweb" }), "/o-mweb")
+})
+
+test("resolveDevBase: defaults to '/' when base is unset", () => {
+    assert.equal(resolveDevBase({}), "/")
+    assert.equal(resolveDevBase(undefined), "/")
+    assert.equal(resolveDevBase({ base: "/" }), "/")
+})
+
+test("resolveDevBase: normalizes to a leading slash, no trailing slash", () => {
+    assert.equal(resolveDevBase({ base: "o-mweb" }), "/o-mweb")
+    assert.equal(resolveDevBase({ base: "/o-mweb/" }), "/o-mweb")
+    assert.equal(resolveDevBase({ base: "  /o-mweb//  " }), "/o-mweb")
+})
+
+// ─── toMountPathPrefix ────────────────────────────────────────────────────────
+
+test("toMountPathPrefix: root maps to empty string for clean URL joins", () => {
+    assert.equal(toMountPathPrefix("/"), "")
+    assert.equal(toMountPathPrefix(""), "")
+    assert.equal(toMountPathPrefix(undefined), "")
+})
+
+test("toMountPathPrefix: trims Vite's trailing slash", () => {
+    assert.equal(toMountPathPrefix("/o-mweb/"), "/o-mweb")
+    assert.equal(toMountPathPrefix("/o-mweb"), "/o-mweb")
+    // The joined result stays single-slashed.
+    assert.equal(`${toMountPathPrefix("/o-mweb/")}/client/index.js`, "/o-mweb/client/index.js")
+    assert.equal(`${toMountPathPrefix("/")}/client/index.js`, "/client/index.js")
+})
+
+// ─── resolveDevFsAllow: security-sensitive allowlist merge ─────────────────────
+
+const FRAMEWORK = ["/app/src", "/framework/dist/vite"]
+
+test("resolveDevFsAllow: framework paths always present, none provided", () => {
+    assert.deepEqual(resolveDevFsAllow(undefined, FRAMEWORK), FRAMEWORK)
+    assert.deepEqual(resolveDevFsAllow({}, FRAMEWORK), FRAMEWORK)
+})
+
+test("resolveDevFsAllow: apps may EXTEND but never drop framework paths", () => {
+    const result = resolveDevFsAllow({ allow: ["/extra/pkg"] }, FRAMEWORK)
+    assert.deepEqual(result, ["/app/src", "/framework/dist/vite", "/extra/pkg"])
+})
+
+test("resolveDevFsAllow: non-array allow is ignored (no widening via bad input)", () => {
+    assert.deepEqual(resolveDevFsAllow({ allow: "/" }, FRAMEWORK), FRAMEWORK)
+    assert.deepEqual(resolveDevFsAllow({ allow: null }, FRAMEWORK), FRAMEWORK)
+})
+
+// ─── buildDevServer: precedence + security ────────────────────────────────────
+
+test("buildDevServer: hmr defaults to true in dev", () => {
+    const server = buildDevServer({}, { frameworkPaths: FRAMEWORK, isProduction: false })
+    assert.equal(server.hmr, true)
+})
+
+test("buildDevServer: hmr is false in production", () => {
+    const server = buildDevServer({ hmr: { clientPort: 443 } }, { frameworkPaths: FRAMEWORK, isProduction: true })
+    assert.equal(server.hmr, false)
+})
+
+test("buildDevServer: app hmr overrides are honored in dev", () => {
+    const hmr = { clientPort: 443, path: "__vite_hmr" }
+    const server = buildDevServer({ hmr }, { frameworkPaths: FRAMEWORK, isProduction: false })
+    assert.deepEqual(server.hmr, hmr)
+})
+
+test("buildDevServer: passthrough keys (proxy/allowedHosts) are forwarded", () => {
+    const server = buildDevServer(
+        { allowedHosts: ["local.example.com"], proxy: { "/api": "http://localhost:9000" } },
+        { frameworkPaths: FRAMEWORK, isProduction: false }
+    )
+    assert.deepEqual(server.allowedHosts, ["local.example.com"])
+    assert.deepEqual(server.proxy, { "/api": "http://localhost:9000" })
+})
+
+test("buildDevServer: app fs cannot replace the allowlist, only extend it", () => {
+    const server = buildDevServer(
+        { fs: { allow: ["/extra"] } },
+        { frameworkPaths: FRAMEWORK, isProduction: false }
+    )
+    assert.deepEqual(server.fs.allow, ["/app/src", "/framework/dist/vite", "/extra"])
+})
+
+test("buildDevServer: app cannot relax fs.strict or clobber fs via overrides", () => {
+    const server = buildDevServer(
+        { fs: { allow: ["/"], strict: false } },
+        { frameworkPaths: FRAMEWORK, isProduction: false }
+    )
+    // strict is dropped entirely (framework keeps Vite's secure default), and
+    // the framework paths remain — "/" is merely appended, not a replacement.
+    assert.equal(server.fs.strict, undefined)
+    assert.ok(server.fs.allow.includes("/app/src"))
+})
+
+test("buildDevServer: 'base' is not leaked into the server block", () => {
+    const server = buildDevServer({ base: "/o-mweb" }, { frameworkPaths: FRAMEWORK, isProduction: false })
+    assert.equal(server.base, undefined)
+})