arcway 0.1.0

package/server/pages/build-client.js

@@ -0,0 +1,187 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import esbuild from 'esbuild';
+import { resolveLayoutChain, resolveLoadingChain } from './discovery.js';
+import { clientIsolationPlugin } from './build-plugins.js';
+import { patternToFileName, layoutDirToFileName } from './build-server.js';
+import { reactRefreshPlugin } from './hmr.js';
+async function buildClientBundles(
+  pages,
+  layouts,
+  outDir,
+  target,
+  minify,
+  rootDir,
+  loadings = [],
+  nodeEnv = 'production',
+  devMode = false,
+) {
+  const clientDir = path.join(outDir, 'client');
+  const bundles = new Map();
+  const navBundles = new Map();
+  const layoutNavBundles = new Map();
+  const loadingNavBundles = new Map();
+  const entryPoints = {};
+  const tempDir = path.join(outDir, '.hydration-entries');
+  await fs.mkdir(tempDir, { recursive: true });
+  for (const page of pages) {
+    const outName = patternToFileName(page.pattern);
+    const layoutChain = resolveLayoutChain(page.pattern, layouts);
+    const loadingChain = resolveLoadingChain(page.pattern, loadings);
+    const entryContent = generateHydrationEntry(page.filePath, layoutChain, loadingChain);
+    const entryPath = path.join(tempDir, `${outName}.tsx`);
+    await fs.mkdir(path.dirname(entryPath), { recursive: true });
+    await fs.writeFile(entryPath, entryContent);
+    entryPoints[outName] = entryPath;
+  }
+  for (const page of pages) {
+    const navName = `nav_${patternToFileName(page.pattern)}`;
+    const importPath = page.filePath.replace(/\\/g, '/');
+    const navContent = `export { default } from '${importPath}';
+`;
+    const navPath = path.join(tempDir, `${navName}.tsx`);
+    await fs.mkdir(path.dirname(navPath), { recursive: true });
+    await fs.writeFile(navPath, navContent);
+    entryPoints[navName] = navPath;
+  }
+  for (const layout of layouts) {
+    const layoutName = `nav_layout_${layoutDirToFileName(layout.dirPath)}`;
+    const importPath = layout.filePath.replace(/\\/g, '/');
+    const navContent = `export { default } from '${importPath}';
+`;
+    const navPath = path.join(tempDir, `${layoutName}.tsx`);
+    await fs.mkdir(path.dirname(navPath), { recursive: true });
+    await fs.writeFile(navPath, navContent);
+    entryPoints[layoutName] = navPath;
+  }
+  for (const loading of loadings) {
+    const loadingName = `nav_loading_${layoutDirToFileName(loading.dirPath)}`;
+    const importPath = loading.filePath.replace(/\\/g, '/');
+    const navContent = `export { default } from '${importPath}';
+`;
+    const navPath = path.join(tempDir, `${loadingName}.tsx`);
+    await fs.mkdir(path.dirname(navPath), { recursive: true });
+    await fs.writeFile(navPath, navContent);
+    entryPoints[loadingName] = navPath;
+  }
+  const projectRequire = createRequire(path.join(rootDir, 'package.json'));
+  const reactAlias = {};
+  for (const pkg of ['react', 'react-dom']) {
+    try {
+      reactAlias[pkg] = path.dirname(projectRequire.resolve(`${pkg}/package.json`));
+    } catch {}
+  }
+  const result = await esbuild.build({
+    entryPoints,
+    outdir: clientDir,
+    format: 'esm',
+    platform: 'browser',
+    target,
+    bundle: true,
+    splitting: true,
+    entryNames: '[name]-[hash]',
+    chunkNames: 'chunks/[name]-[hash]',
+    jsx: 'automatic',
+    loader: { '.js': 'jsx' },
+    minify,
+    sourcemap: true,
+    metafile: true,
+    alias: reactAlias,
+    define: { 'process.env.NODE_ENV': JSON.stringify(nodeEnv) },
+    plugins: [...(devMode ? [reactRefreshPlugin(rootDir)] : []), clientIsolationPlugin()],
+  });
+  await fs.rm(tempDir, { recursive: true, force: true });
+  const entryToPattern = new Map();
+  const entryToNavPattern = new Map();
+  const entryToLayoutDir = new Map();
+  for (const page of pages) {
+    const outName = patternToFileName(page.pattern);
+    entryToPattern.set(path.join(tempDir, `${outName}.tsx`), page.pattern);
+    entryToNavPattern.set(path.join(tempDir, `nav_${outName}.tsx`), page.pattern);
+  }
+  for (const layout of layouts) {
+    const layoutName = `nav_layout_${layoutDirToFileName(layout.dirPath)}`;
+    entryToLayoutDir.set(path.join(tempDir, `${layoutName}.tsx`), layout.dirPath);
+  }
+  const entryToLoadingDir = new Map();
+  for (const loading of loadings) {
+    const loadingName = `nav_loading_${layoutDirToFileName(loading.dirPath)}`;
+    entryToLoadingDir.set(path.join(tempDir, `${loadingName}.tsx`), loading.dirPath);
+  }
+  const sharedChunks = [];
+  for (const [outputPath, meta] of Object.entries(result.metafile.outputs)) {
+    const relPath = path.relative(outDir, outputPath).replace(/\\/g, '/');
+    if (outputPath.endsWith('.map')) continue;
+    if (relPath.startsWith('client/chunks/')) {
+      sharedChunks.push(relPath);
+      continue;
+    }
+    if (meta.entryPoint) {
+      const absEntry = path.resolve(meta.entryPoint);
+      for (const [entryPath, pattern] of entryToPattern) {
+        if (absEntry === entryPath) {
+          bundles.set(pattern, relPath);
+          break;
+        }
+      }
+      for (const [entryPath, pattern] of entryToNavPattern) {
+        if (absEntry === entryPath) {
+          navBundles.set(pattern, relPath);
+          break;
+        }
+      }
+      for (const [entryPath, dirPath] of entryToLayoutDir) {
+        if (absEntry === entryPath) {
+          layoutNavBundles.set(dirPath, relPath);
+          break;
+        }
+      }
+      for (const [entryPath, dirPath] of entryToLoadingDir) {
+        if (absEntry === entryPath) {
+          loadingNavBundles.set(dirPath, relPath);
+          break;
+        }
+      }
+    }
+  }
+  return {
+    bundles,
+    navBundles,
+    layoutNavBundles,
+    loadingNavBundles,
+    sharedChunks,
+    ...(devMode ? { metafile: result.metafile } : {}),
+  };
+}
+function generateHydrationEntry(componentPath, layouts = [], loadings = []) {
+  const importPath = componentPath.replace(/\\/g, '/');
+  const imports = [
+    `import { hydrateRoot } from 'react-dom/client';`,
+    `import { ApiProvider, Router } from 'arcway/lib/client';`,
+  ];
+  imports.push(`import Component from '${importPath}';`);
+  const layoutNames = [];
+  for (let i = 0; i < layouts.length; i++) {
+    const layoutImportPath = layouts[i].filePath.replace(/\\/g, '/');
+    imports.push(`import Layout${i} from '${layoutImportPath}';`);
+    layoutNames.push(`Layout${i}`);
+  }
+  const loadingNames = [];
+  for (let i = 0; i < loadings.length; i++) {
+    const loadingImportPath = loadings[i].filePath.replace(/\\/g, '/');
+    imports.push(`import Loading${i} from '${loadingImportPath}';`);
+    loadingNames.push(`Loading${i}`);
+  }
+  const layoutsArray = layoutNames.length > 0 ? `[${layoutNames.join(', ')}]` : '[]';
+  const loadingsArray = loadingNames.length > 0 ? `[${loadingNames.join(', ')}]` : '[]';
+  return `${imports.join('\n')}
+
+const container = document.getElementById('__app');
+const propsEl = document.getElementById('__app_props');
+const props = propsEl ? JSON.parse(propsEl.textContent || '{}') : {};
+
+hydrateRoot(container!, <ApiProvider><Router initialPath={window.location.pathname} initialParams={props} initialComponent={Component} initialLayouts={${layoutsArray}} initialLoadings={${loadingsArray}} /></ApiProvider>);
+`;
+}
+export { buildClientBundles, generateHydrationEntry };

package/server/pages/build-css.js

@@ -0,0 +1,47 @@
+import path from 'node:path';
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import esbuild from 'esbuild';
+import postcss from 'postcss';
+import tailwindPostcss from '@tailwindcss/postcss';
+async function buildCssBundle(pagesDir, outDir, minify, stylesPath, fontFaceCss) {
+  try {
+    await fs.access(pagesDir);
+  } catch {
+    // Pages directory doesn't exist — no CSS to build
+    return void 0;
+  }
+  let cssSource;
+  if (stylesPath) {
+    cssSource = `@import ${JSON.stringify(stylesPath)};`;
+  } else {
+    const require2 = createRequire(import.meta.url);
+    const tailwindCssPath = path.dirname(require2.resolve('tailwindcss/package.json'));
+    const tailwindEntryPath = path.join(tailwindCssPath, 'index.css');
+    cssSource = [
+      `@import ${JSON.stringify(tailwindEntryPath)};`,
+      `@source ${JSON.stringify(pagesDir)};`,
+    ].join('\n');
+  }
+  const processor = postcss([tailwindPostcss()]);
+  const result = await processor.process(cssSource, {
+    from: stylesPath ?? path.join(pagesDir, '__virtual_entry.css'),
+    to: path.join(outDir, 'client', 'styles.css'),
+  });
+  let css = fontFaceCss
+    ? `${fontFaceCss}
+
+${result.css}`
+    : result.css;
+  if (minify) {
+    const minified = await esbuild.transform(css, { loader: 'css', minify: true });
+    css = minified.code;
+  }
+  const hash = crypto.createHash('sha256').update(css).digest('hex').slice(0, 8);
+  const cssFileName = `styles-${hash}.css`;
+  const outFile = path.join(outDir, 'client', cssFileName);
+  await fs.writeFile(outFile, css);
+  return `client/${cssFileName}`;
+}
+export { buildCssBundle };

package/server/pages/build-manifest.js

@@ -0,0 +1,55 @@
+import {
+  resolveLayoutChain,
+  resolveLoadingChain,
+  resolvePageMiddlewareChain,
+} from './discovery.js';
+function generateManifest(
+  pages,
+  layouts,
+  loadings,
+  middlewares,
+  serverBundles,
+  layoutServerBundles,
+  middlewareServerBundles,
+  clientResult,
+) {
+  const entries = [];
+  for (const page of pages) {
+    const serverBundle = serverBundles.get(page.pattern);
+    const clientBundle = clientResult.bundles.get(page.pattern);
+    const navBundle = clientResult.navBundles.get(page.pattern);
+    if (!serverBundle || !clientBundle || !navBundle) continue;
+    const layoutChain = resolveLayoutChain(page.pattern, layouts);
+    const layoutServerBundlePaths = layoutChain
+      .map((l) => layoutServerBundles.get(l.dirPath))
+      .filter((p) => p !== void 0);
+    const layoutClientBundlePaths = layoutChain
+      .map((l) => clientResult.layoutNavBundles.get(l.dirPath))
+      .filter((p) => p !== void 0);
+    const loadingChain = resolveLoadingChain(page.pattern, loadings);
+    const loadingClientBundlePaths = loadingChain
+      .map((l) => clientResult.loadingNavBundles.get(l.dirPath))
+      .filter((p) => p !== void 0);
+    const middlewareChain = resolvePageMiddlewareChain(page.pattern, middlewares);
+    const middlewareServerBundlePaths = middlewareChain
+      .map((m) => middlewareServerBundles.get(m.dirPath))
+      .filter((p) => p !== void 0);
+    entries.push({
+      pattern: page.pattern,
+      paramNames: page.paramNames,
+      ...(page.catchAllParam ? { catchAllParam: page.catchAllParam } : {}),
+      serverBundle,
+      clientBundle,
+      navBundle,
+      layoutServerBundles: layoutServerBundlePaths,
+      layoutClientBundles: layoutClientBundlePaths,
+      loadingClientBundles: loadingClientBundlePaths,
+      middlewareServerBundles: middlewareServerBundlePaths,
+    });
+  }
+  return {
+    entries,
+    sharedChunks: clientResult.sharedChunks,
+  };
+}
+export { generateManifest };

package/server/pages/build-plugins.js

@@ -0,0 +1,75 @@
+import { createRequire } from 'node:module';
+import { NODE_BUILTINS, SERVER_ONLY_PACKAGES } from '../constants.js';
+function serverExternalsPlugin() {
+  const resolvedCache = new Map();
+  return {
+    name: 'arcway-server-externals',
+    setup(build) {
+      build.onResolve({ filter: /^[^.\/\#]/ }, (args) => {
+        if (/^[A-Za-z]:/.test(args.path)) return void 0;
+        if (args.path.startsWith('node:')) return void 0;
+        const parts = args.path.split('/');
+        const pkgName =
+          args.path.startsWith('@') && parts.length >= 2 ? `${parts[0]}/${parts[1]}` : parts[0];
+        if (!resolvedCache.has(pkgName)) {
+          resolvedCache.set(pkgName, isTypeScriptPackage(pkgName, args.resolveDir));
+        }
+        if (resolvedCache.get(pkgName)) return void 0;
+        return { path: args.path, external: true };
+      });
+    },
+  };
+}
+function isTypeScriptPackage(pkgName, resolveDir) {
+  try {
+    const require2 = createRequire(resolveDir + '/');
+    const resolved = require2.resolve(pkgName);
+    return /\.tsx?$/.test(resolved);
+  } catch {
+    return false;
+  }
+}
+function clientIsolationPlugin() {
+  return {
+    name: 'arcway-client-isolation',
+    setup(build) {
+      const STUB_NAMESPACE = 'arcway-empty-stub';
+      build.onLoad({ filter: /.*/, namespace: STUB_NAMESPACE }, () => {
+        return { contents: 'export default {};', loader: 'js' };
+      });
+      build.onResolve({ filter: /.*/ }, (args) => {
+        if (NODE_BUILTINS.has(args.path)) {
+          return { path: args.path, namespace: STUB_NAMESPACE };
+        }
+        return void 0;
+      });
+      build.onResolve({ filter: /.*/ }, (args) => {
+        const parts = args.path.split('/');
+        const pkgName =
+          args.path.startsWith('@') && parts.length >= 2 ? `${parts[0]}/${parts[1]}` : parts[0];
+        if (SERVER_ONLY_PACKAGES.has(pkgName)) {
+          return { path: args.path, namespace: STUB_NAMESPACE };
+        }
+        return void 0;
+      });
+      build.onResolve({ filter: /^arcway(?:\/|$)/ }, (args) => {
+        if (
+          args.path === 'arcway/lib/client' ||
+          args.path.startsWith('arcway/lib/client/') ||
+          args.path === 'arcway/ui' ||
+          args.path.startsWith('arcway/ui/')
+        ) {
+          return void 0;
+        }
+        return {
+          errors: [
+            {
+              text: `Cannot import "${args.path}" in a page component. "${args.path}" contains server-only code (database, auth, etc.) that cannot run in the browser. Use "arcway/lib/client" for client-safe APIs (useApi, useMutation, etc.) or import the package directly (e.g. import { type } from "arktype" instead of from "arcway").`,
+            },
+          ],
+        };
+      });
+    },
+  };
+}
+export { clientIsolationPlugin, serverExternalsPlugin };

package/server/pages/build-server.js

@@ -0,0 +1,115 @@
+import path from 'node:path';
+import esbuild from 'esbuild';
+import { serverExternalsPlugin } from './build-plugins.js';
+function patternToFileName(pattern) {
+  if (pattern === '/') return '_index';
+  return pattern
+    .slice(1)
+    .replace(/\*(\w+)\?/g, '_catchopt_$1')
+    .replace(/\*(\w+)/g, '_catch_$1')
+    .replace(/:(\w+)/g, '_$1');
+}
+function layoutDirToFileName(dirPath) {
+  if (dirPath === '') return 'root';
+  return dirPath.replace(/[\\/]/g, '_');
+}
+async function buildServerBundles(pages, outDir, target) {
+  const serverDir = path.join(outDir, 'server');
+  const resultMap = new Map();
+  for (const page of pages) {
+    const outName = patternToFileName(page.pattern);
+    const outFile = path.join(serverDir, `${outName}.js`);
+    await esbuild.build({
+      entryPoints: [page.filePath],
+      outfile: outFile,
+      format: 'esm',
+      platform: 'node',
+      target,
+      bundle: true,
+      jsx: 'automatic',
+      loader: { '.js': 'jsx' },
+      sourcemap: true,
+      plugins: [serverExternalsPlugin()],
+    });
+    resultMap.set(page.pattern, path.relative(outDir, outFile).replace(/\\/g, '/'));
+  }
+  return resultMap;
+}
+async function buildLayoutServerBundles(layouts, outDir, target) {
+  const serverDir = path.join(outDir, 'server');
+  const resultMap = new Map();
+  for (const layout of layouts) {
+    const outName = layoutDirToFileName(layout.dirPath);
+    const outFile = path.join(serverDir, `_layout_${outName}.js`);
+    await esbuild.build({
+      entryPoints: [layout.filePath],
+      outfile: outFile,
+      format: 'esm',
+      platform: 'node',
+      target,
+      bundle: true,
+      jsx: 'automatic',
+      loader: { '.js': 'jsx' },
+      sourcemap: true,
+      plugins: [serverExternalsPlugin()],
+    });
+    resultMap.set(layout.dirPath, path.relative(outDir, outFile).replace(/\\/g, '/'));
+  }
+  return resultMap;
+}
+async function buildMiddlewareServerBundles(middlewares, outDir, target) {
+  const serverDir = path.join(outDir, 'server');
+  const resultMap = new Map();
+  for (const mw of middlewares) {
+    const outName = layoutDirToFileName(mw.dirPath);
+    const outFile = path.join(serverDir, `_middleware_${outName}.js`);
+    await esbuild.build({
+      entryPoints: [mw.filePath],
+      outfile: outFile,
+      format: 'esm',
+      platform: 'node',
+      target,
+      bundle: true,
+      sourcemap: true,
+      plugins: [serverExternalsPlugin()],
+    });
+    resultMap.set(mw.dirPath, path.relative(outDir, outFile).replace(/\\/g, '/'));
+  }
+  return resultMap;
+}
+async function buildErrorPageBundles(errorPages, outDir, target) {
+  const serverDir = path.join(outDir, 'server');
+  const result = {};
+  const builds = [];
+  if (errorPages.errorPage) {
+    builds.push({ filePath: errorPages.errorPage, outName: '_error', key: 'error' });
+  }
+  if (errorPages.notFoundPage) {
+    builds.push({ filePath: errorPages.notFoundPage, outName: '_404', key: 'notFound' });
+  }
+  for (const build of builds) {
+    const outFile = path.join(serverDir, `${build.outName}.js`);
+    await esbuild.build({
+      entryPoints: [build.filePath],
+      outfile: outFile,
+      format: 'esm',
+      platform: 'node',
+      target,
+      bundle: true,
+      jsx: 'automatic',
+      loader: { '.js': 'jsx' },
+      sourcemap: true,
+      plugins: [serverExternalsPlugin()],
+    });
+    result[build.key] = path.relative(outDir, outFile);
+  }
+  return result;
+}
+export {
+  buildErrorPageBundles,
+  buildLayoutServerBundles,
+  buildMiddlewareServerBundles,
+  buildServerBundles,
+  layoutDirToFileName,
+  patternToFileName,
+};

package/server/pages/build.js

@@ -0,0 +1,116 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import {
+  discoverPages,
+  discoverLayouts,
+  discoverLoadings,
+  discoverPageMiddleware,
+  discoverErrorPages,
+  discoverStyles,
+} from './discovery.js';
+import {
+  buildServerBundles,
+  buildLayoutServerBundles,
+  buildMiddlewareServerBundles,
+  buildErrorPageBundles,
+} from './build-server.js';
+import { buildClientBundles } from './build-client.js';
+import { buildCssBundle } from './build-css.js';
+import { generateManifest } from './build-manifest.js';
+import { resolveFonts } from './fonts.js';
+import { buildHmrRuntimeBundle } from './hmr.js';
+async function buildPages(options) {
+  const { rootDir } = options;
+  const pagesDir = options.pagesDir ?? path.join(rootDir, 'pages');
+  const outDir = path.resolve(rootDir, options.outDir ?? '.build/pages');
+  const serverTarget = options.serverTarget ?? 'node22';
+  const clientTarget = options.clientTarget ?? 'es2022';
+  const minify = options.minify ?? true;
+  const devMode = options.devMode ?? false;
+  const [pages, layouts, loadings, middlewares, errorPages, stylesPath] = await Promise.all([
+    discoverPages(pagesDir),
+    discoverLayouts(pagesDir),
+    discoverLoadings(pagesDir),
+    discoverPageMiddleware(pagesDir),
+    discoverErrorPages(pagesDir),
+    discoverStyles(pagesDir),
+  ]);
+  if (pages.length === 0) {
+    return { pageCount: 0, outDir, manifest: { entries: [], sharedChunks: [] } };
+  }
+  await fs.rm(outDir, { recursive: true, force: true });
+  await fs.mkdir(path.join(outDir, 'server'), { recursive: true });
+  await fs.mkdir(path.join(outDir, 'client'), { recursive: true });
+  let fontFaceCss;
+  let fontPreloadHtml;
+  if (options.fonts && options.fonts.length > 0) {
+    const publicDir = path.join(rootDir, 'public');
+    const fontResult = await resolveFonts(options.fonts, publicDir);
+    if (fontResult.fontFaceCss) fontFaceCss = fontResult.fontFaceCss;
+    if (fontResult.preloadHtml) fontPreloadHtml = fontResult.preloadHtml;
+  }
+  const builds = [
+    buildServerBundles(pages, outDir, serverTarget),
+    buildLayoutServerBundles(layouts, outDir, serverTarget),
+    buildMiddlewareServerBundles(middlewares, outDir, serverTarget),
+    buildClientBundles(
+      pages,
+      layouts,
+      outDir,
+      clientTarget,
+      minify,
+      rootDir,
+      loadings,
+      minify ? 'production' : 'development',
+      devMode,
+    ),
+    buildErrorPageBundles(errorPages, outDir, serverTarget),
+    buildCssBundle(pagesDir, outDir, minify, stylesPath, fontFaceCss),
+  ];
+  if (devMode) builds.push(buildHmrRuntimeBundle(outDir));
+  const [
+    serverResult,
+    layoutServerResult,
+    middlewareServerResult,
+    clientResult,
+    errorBundles,
+    cssBundle,
+  ] = await Promise.all(builds);
+  const manifest = generateManifest(
+    pages,
+    layouts,
+    loadings,
+    middlewares,
+    serverResult,
+    layoutServerResult,
+    middlewareServerResult,
+    clientResult,
+  );
+  if (errorBundles.error) manifest.errorBundle = errorBundles.error;
+  if (errorBundles.notFound) manifest.notFoundBundle = errorBundles.notFound;
+  if (cssBundle) manifest.cssBundle = cssBundle;
+  if (fontPreloadHtml) manifest.fontPreloadHtml = fontPreloadHtml;
+  await fs.writeFile(path.join(outDir, 'pages-manifest.json'), JSON.stringify(manifest, null, 2));
+  return {
+    pageCount: pages.length,
+    outDir,
+    manifest,
+    ...(devMode && clientResult.metafile ? { clientMetafile: clientResult.metafile } : {}),
+  };
+}
+import { patternToFileName, layoutDirToFileName } from './build-server.js';
+import { generateHydrationEntry } from './build-client.js';
+import { generateManifest as generateManifest2 } from './build-manifest.js';
+import { serverExternalsPlugin, clientIsolationPlugin } from './build-plugins.js';
+import { NODE_BUILTINS, SERVER_ONLY_PACKAGES } from '../constants.js';
+export {
+  NODE_BUILTINS,
+  SERVER_ONLY_PACKAGES,
+  buildPages,
+  generateHydrationEntry,
+  generateManifest2 as generateManifest,
+  layoutDirToFileName,
+  patternToFileName,
+  clientIsolationPlugin,
+  serverExternalsPlugin,
+};