glashjs 0.11.1 → 0.12.0

package/README.md

@@ -127,6 +127,37 @@ Hydration is **CSP-safe**: server props ride in a non-executed `<script type="ap
 
 **Nested layouts** (`_layout.jsx` in any routes dir wrap pages root→leaf, server + hydration), **streaming SSR** (the shell flushes before the component renders — `Transfer-Encoding: chunked`), and **instant HMR** (`glash dev` does an in-place soft re-render on save over SSE — no full reload, no flash, and scroll/focus/form-input are preserved across the swap) are all in. **Suspense streaming** is in too — wrap a data-dependent subtree in `<Suspense fallback={…}>` (from `preact/compat`) and the shell + fallback flush immediately, then each boundary streams in as its data resolves (`renderToPipeableStream`), with preact's inline swap scripts nonce-injected so the strict CSP holds. **Honest scope:** uses Preact (React-compatible via `preact/compat`), not React; HMR preserves DOM/scroll/input state but **not** component `useState` (that's React-Fast-Refresh via `@prefresh`, still ahead).
 
+## Migrating from Next.js
+
+glashjs is a Next.js alternative with the same conventions, so an existing Next app can be moved over with one command:
+
+```bash
+npx glashjs migrate          # scaffold routes/ from your app/ or pages/ + a report
+npx glashjs migrate --dry-run  # preview the mapping first, write nothing
+```
+
+`glashjs migrate` does the **mechanical** migration and writes a `MIGRATION.md` punch-list — it never deletes your Next code:
+
+| Next.js | → | glashjs |
+|---|---|---|
+| `app/page.tsx` | → | `routes/index.tsx` |
+| `app/blog/[slug]/page.tsx` | → | `routes/blog/[slug].tsx` |
+| `app/layout.tsx` | → | `routes/_layout.tsx` |
+| `app/api/x/route.ts` (`GET`/`POST`) | → | `routes/api/x.ts` (same `GET`/`POST` exports) |
+| `pages/index.tsx`, `pages/api/x.ts` | → | `routes/index.tsx`, `routes/api/x.ts` |
+| `middleware.ts` | → | `routes/_middleware.mjs` |
+| `getServerSideProps` | → | `getServerData(ctx)` (auto-renamed) |
+| `next/link`, `next/image` | → | `glashjs/link`, `glashjs/image` (auto-rewritten) |
+
+Your **React/Next components run as-is**: glashjs aliases `react`/`react-dom` → `preact/compat` in its build, and runs **TypeScript** routes/API/middleware directly (esbuild). `'use client'` is stripped (glashjs hydrates by default).
+
+```bash
+npm i glashjs preact preact-render-to-string esbuild
+npx glashjs dev      # then work the TODOs the report flagged
+```
+
+**Honest scope:** the mechanical 80% is automatic. **React Server Components**, **Server Actions**, `getStaticProps` (SSG), and `next/navigation`/`next/headers`/Supabase-server-auth are **flagged in `MIGRATION.md` for hands-on porting** — they don't map 1:1 and glashjs won't pretend they do.
+
 ## Usage
 
 ```js

package/bin/glash.mjs

@@ -7,6 +7,7 @@ import { optimizeAssets } from '../src/assets/optimize.mjs';
 import { createGlashServer } from '../src/server/server.mjs';
 import { deploy } from '../src/deploy.mjs';
 import { update } from '../src/update.mjs';
+import { migrate } from '../src/migrate.mjs';
 
 const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 const [, , cmd, ...rest] = process.argv;
@@ -61,6 +62,9 @@ async function main() {
     case 'upgrade':
       await update({ root: arg('--root', process.cwd()) });
       break;
+    case 'migrate':
+      await migrate({ root: arg('--root', process.cwd()), dryRun: rest.includes('--dry-run') });
+      break;
     case 'dev':
       await serve(true);
       break;
@@ -88,6 +92,7 @@ Usage: (run as "glashjs <cmd>"; "glash <cmd>" also works unless the glashdb depl
   glashjs dev [--port 3000]     Run the dev server (routing, SSR, API, live reload) + Network preview URL
   glashjs serve [--port 3000]   Run the production server over routes/ + built assets
   glashjs build [--root <dir>]  Optimize assets, precompile routes, generate offline SW + PWA + security
+  glashjs migrate [--dry-run]   Migrate a Next.js project to glashjs (scaffold routes/ + report)
   glashjs update                Update glashjs to the latest published version
   glashjs deploy [--dry-run]    Build, then deploy to glashdb (hands off to the glashdb CLI)
   glashjs optimize [<dir>]      Just run the asset optimizer over a directory

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glashjs",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "glashjs — a web framework built on top of Next.js: file-based routing, SSR, API routes, JSX components with client hydration, nested layouts, streaming SSR, a best-in-class build-time asset optimizer, offline PWA layer, animated favicon, and secure-by-default headers. Zero mandatory dependencies.",
   "type": "module",
   "bin": {

package/src/index.mjs

@@ -3,14 +3,15 @@ export { defineConfig, loadConfig, DEFAULT_CONFIG } from './config.mjs';
 export { build } from './build.mjs';
 export { deploy } from './deploy.mjs';
 export { update } from './update.mjs';
+export { migrate } from './migrate.mjs';
 export { optimizeAssets } from './assets/optimize.mjs';
 export { generateAnimatedFavicon } from './assets/animated-favicon.mjs';
 export { generateServiceWorker } from './offline/generate-sw.mjs';
 export { securityHeaders, buildCsp, sri, glashSecurity } from './security/headers.mjs';
 export { createGlashServer, json, redirect } from './server/server.mjs';
 export { discoverRoutes, matchRoute, findMiddleware } from './server/router.mjs';
-export { html, raw, escapeHtml, renderDocument } from './server/html.mjs';
-export { Image } from './components/image.mjs';
-export { Video } from './components/video.mjs';
-export { Link } from './components/link.mjs';
-export { renderMeta } from './server/html.mjs';
+export { html, raw, escapeHtml, renderDocument, renderMeta } from './server/html.mjs';
+// NOTE: <Image>/<Video>/<Link> are Preact components, so they live on subpaths
+// (glashjs/image, glashjs/video, glashjs/link) and are NOT re-exported here —
+// otherwise importing anything from 'glashjs' would require preact to be
+// installed, breaking the zero-dependency core (html/json/createGlashServer/build).

package/src/migrate.mjs

@@ -0,0 +1,179 @@
+// glashjs migrate — convert a Next.js project to glashjs conventions.
+// ---------------------------------------------------------------------------
+// Honest scope: this does the MECHANICAL migration (file/route mapping, import
+// rewrites, config + scripts) and writes a MIGRATION.md report listing exactly
+// what still needs hands-on porting (RSC/server actions/SSG/next-specific APIs).
+// It never deletes your Next code — it scaffolds `routes/` alongside it.
+import { promises as fs, existsSync } from 'node:fs';
+import path from 'node:path';
+
+const PAGE_EXT = /\.(tsx|jsx|ts|js)$/;
+
+// next import -> glashjs equivalent (safe, mechanical rewrites)
+const IMPORT_REWRITES = [
+  [/(['"])next\/link\1/g, "'glashjs/link'"],
+  [/(['"])next\/image\1/g, "'glashjs/image'"],
+];
+
+// patterns that need a human — surfaced in the report, not silently "fixed"
+const MANUAL = [
+  [/from\s+['"]next\/navigation['"]/, 'next/navigation (useRouter/usePathname/redirect) → glashjs <Link> + redirect() + ctx.url'],
+  [/from\s+['"]next\/headers['"]/, 'next/headers (cookies/headers) → read ctx.headers in getServerData / API handlers'],
+  [/from\s+['"]next\/font/, 'next/font → load fonts via <link rel="preload"> or CSS @font-face'],
+  [/getServerSideProps/, 'getServerSideProps → rename to `export function getServerData(ctx)` (same role)'],
+  [/getStaticProps|getStaticPaths/, 'getStaticProps/Paths (SSG) → use getServerData (SSR) or precompute at build'],
+  [/['"]use server['"]/, 'Server Actions ("use server") → port to a glashjs API route (routes/api/*)'],
+  [/createServerClient|auth\.getUser\(\)|supabase\.auth/, 'Supabase server auth → re-wire via glashjs _middleware.mjs + API routes'],
+  [/export\s+const\s+(dynamic|revalidate|fetchCache)/, 'Route segment config (dynamic/revalidate) → handle in getServerData / cache headers'],
+];
+
+function srcDirs(root) {
+  // Next supports app/ or pages/, optionally under src/.
+  const bases = ['app', 'pages', 'src/app', 'src/pages'];
+  return bases.map((b) => path.join(root, b)).filter(existsSync);
+}
+
+async function walk(dir) {
+  const out = [];
+  for (const e of await fs.readdir(dir, { withFileTypes: true })) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) out.push(...(await walk(full)));
+    else out.push(full);
+  }
+  return out;
+}
+
+// app/ route folder -> URL path (strip page/route/layout file, route groups
+// "(grp)", keep [param]). Handles root-level files (no leading slash) too.
+function appPath(rel) {
+  let p = rel.replace(/\\/g, '/').replace(/(^|\/)(page|route|layout)\.(tsx|jsx|ts|js)$/, '');
+  p = p.split('/').filter((seg) => seg && !(seg.startsWith('(') && seg.endsWith(')'))).join('/');
+  return p;
+}
+
+// Map one Next file -> { to, kind } in glashjs routes/, or null to skip.
+function mapFile(rel, router) {
+  const base = path.basename(rel);
+  if (router === 'app') {
+    if (/^page\.(tsx|jsx|ts|js)$/.test(base)) {
+      const p = appPath(rel); return { to: `routes/${p || 'index'}.tsx`, kind: 'page' };
+    }
+    if (/^layout\.(tsx|jsx|ts|js)$/.test(base)) {
+      const p = appPath(rel); return { to: `routes/${p ? p + '/' : ''}_layout.tsx`, kind: 'layout' };
+    }
+    if (/^route\.(ts|js)$/.test(base)) {
+      const p = appPath(rel); const api = p.startsWith('api/') ? p : `api/${p}`; return { to: `routes/${api}.ts`, kind: 'api' };
+    }
+    return null;
+  }
+  // pages/ router
+  if (rel.startsWith('api/')) {
+    const p = rel.replace(PAGE_EXT, ''); return { to: `routes/${p}.ts`, kind: 'api' };
+  }
+  if (base.startsWith('_app') || base.startsWith('_document')) {
+    return { to: `routes/_layout.tsx`, kind: 'layout' };
+  }
+  let p = rel.replace(PAGE_EXT, '').replace(/\/index$/, '');
+  if (p === 'index') p = '';
+  return { to: `routes/${p ? p : 'index'}.tsx`, kind: 'page' };
+}
+
+function transform(code, kind) {
+  let out = code;
+  const notes = [];
+  // strip the "use client" directive (glashjs hydrates components by default)
+  out = out.replace(/^\s*['"]use client['"];?\s*\n/m, '');
+  for (const [re, to] of IMPORT_REWRITES) out = out.replace(re, to);
+  // getServerSideProps -> getServerData (best-effort rename of the export)
+  out = out.replace(/export\s+(async\s+)?function\s+getServerSideProps/, 'export $1function getServerData');
+  for (const [re, msg] of MANUAL) if (re.test(code)) notes.push(msg);
+  const header = `// ⤷ auto-migrated from Next.js by \`glashjs migrate\`. Review TODOs below.\n` +
+    (notes.length ? notes.map((n) => `// TODO(glashjs): ${n}`).join('\n') + '\n' : '');
+  return { code: header + out, notes };
+}
+
+export async function migrate({ root = process.cwd(), dryRun = false, log = console.log } = {}) {
+  const dirs = srcDirs(root);
+  if (!dirs.length) {
+    log('No Next.js app/ or pages/ directory found — nothing to migrate.');
+    return { migrated: 0 };
+  }
+  log(`glashjs migrate ${dryRun ? '(dry run) ' : ''}— scanning ${dirs.map((d) => path.relative(root, d)).join(', ')}\n`);
+
+  const report = [];
+  let migrated = 0;
+  const manualItems = new Set();
+
+  for (const dir of dirs) {
+    const router = path.basename(dir) === 'app' ? 'app' : 'pages';
+    for (const file of await walk(dir)) {
+      if (!PAGE_EXT.test(file)) continue;
+      const rel = path.relative(dir, file).replace(/\\/g, '/');
+      const mapped = mapFile(rel, router);
+      if (!mapped) continue;
+      const target = path.join(root, mapped.to);
+      const src = await fs.readFile(file, 'utf8');
+      const { code, notes } = transform(src, mapped.kind);
+      notes.forEach((n) => manualItems.add(n));
+      if (!dryRun) {
+        await fs.mkdir(path.dirname(target), { recursive: true });
+        await fs.writeFile(target, code);
+      }
+      migrated += 1;
+      report.push({ from: `${router}/${rel}`, to: mapped.to, kind: mapped.kind, notes });
+      log(`  ${mapped.kind.padEnd(6)} ${router}/${rel}  →  ${mapped.to}${notes.length ? `  (${notes.length} TODO)` : ''}`);
+    }
+  }
+
+  if (!dryRun) {
+    await ensureConfigAndScripts(root, log);
+    await writeReport(root, report, manualItems);
+  }
+
+  log(`\n${migrated} file(s) ${dryRun ? 'would be' : ''} migrated → routes/`);
+  log(`${manualItems.size} pattern(s) need manual porting — see MIGRATION.md`);
+  log('\nNext steps:');
+  log('  npm i glashjs preact preact-render-to-string esbuild');
+  log('  glashjs dev      # then work through the TODOs in the migrated files');
+  return { migrated, manual: manualItems.size };
+}
+
+async function ensureConfigAndScripts(root, log) {
+  const cfgPath = path.join(root, 'glash.config.mjs');
+  if (!existsSync(cfgPath)) {
+    await fs.writeFile(cfgPath, `import { defineConfig } from 'glashjs/config';\n\nexport default defineConfig({\n  name: 'Migrated app',\n  routesDir: 'routes',\n  offline: true,\n});\n`);
+    log('  + glash.config.mjs');
+  }
+  const pkgPath = path.join(root, 'package.json');
+  try {
+    const pkg = JSON.parse(await fs.readFile(pkgPath, 'utf8'));
+    pkg.scripts = pkg.scripts || {};
+    pkg.scripts['glash:dev'] = 'glashjs dev';
+    pkg.scripts['glash:build'] = 'glashjs build';
+    pkg.scripts['glash:start'] = 'glashjs serve';
+    await fs.writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+    log('  + package.json scripts (glash:dev / glash:build / glash:start)');
+  } catch { /* no package.json */ }
+}
+
+async function writeReport(root, report, manualItems) {
+  const lines = ['# Next.js → glashjs migration report', '',
+    `Auto-migrated **${report.length}** files into \`routes/\`. Your original Next code was left untouched.`, '',
+    '## Files migrated', '', '| Next | glashjs | kind | TODOs |', '|---|---|---|---|'];
+  for (const r of report) lines.push(`| \`${r.from}\` | \`${r.to}\` | ${r.kind} | ${r.notes.length} |`);
+  lines.push('', '## Needs manual porting', '');
+  if (manualItems.size) for (const m of manualItems) lines.push(`- ${m}`);
+  else lines.push('- Nothing detected — but review the migrated components in a browser.');
+  lines.push('', '## Next.js → glashjs cheatsheet', '',
+    '| Next.js | glashjs |', '|---|---|',
+    '| `app/page.tsx` | `routes/index.tsx` |',
+    '| `app/blog/[slug]/page.tsx` | `routes/blog/[slug].tsx` |',
+    '| `app/layout.tsx` | `routes/_layout.tsx` |',
+    '| `app/api/x/route.ts` (GET/POST) | `routes/api/x.ts` (export GET/POST) |',
+    '| `middleware.ts` | `routes/_middleware.mjs` |',
+    '| `getServerSideProps` | `export function getServerData(ctx)` |',
+    '| `next/link` | `glashjs/link` |',
+    '| `next/image` | `glashjs/image` |',
+    '| `useRouter().push` | `<Link>` / `redirect()` |', '');
+  await fs.writeFile(path.join(root, 'MIGRATION.md'), lines.join('\n'));
+}

package/src/server/jsx.mjs

@@ -38,10 +38,42 @@ async function preactRuntime() {
   return { h: _h, renderToString: _renderToString };
 }
 
+// Make migrated React/Next components compile + run under Preact.
+const REACT_ALIAS = {
+  react: 'preact/compat',
+  'react-dom': 'preact/compat',
+  'react-dom/client': 'preact/compat',
+  'react/jsx-runtime': 'preact/jsx-runtime',
+  'react/jsx-dev-runtime': 'preact/jsx-runtime',
+};
+
 export function isComponentRoute(file) {
   return /\.(jsx|tsx)$/.test(file);
 }
 
+/**
+ * Import any route/middleware module. Plain `.mjs`/`.js` import directly (zero
+ * dep); `.ts`/`.tsx`/`.jsx` are esbuild-compiled first (so migrated TypeScript
+ * API routes & middleware run). Used for API routes and `_middleware`.
+ */
+export async function compileModule(file, root, dev) {
+  if (/\.(mjs|js)$/.test(file)) {
+    return import(pathToFileURL(file).href + (dev ? `?t=${Date.now()}` : ''));
+  }
+  const eb = await esbuild();
+  if (!eb) throw new Error('TypeScript routes need esbuild: npm i esbuild');
+  const out = path.join(root, '.glash', 'server', 'mod-' + routeId(file) + '.mjs');
+  if (!dev && existsSync(out)) return import(pathToFileURL(out).href);
+  await fs.mkdir(path.dirname(out), { recursive: true });
+  await eb.build({
+    entryPoints: [file], bundle: true, platform: 'node', format: 'esm',
+    jsx: 'automatic', jsxImportSource: 'preact',
+    external: ['preact', 'preact/*', 'preact-render-to-string'],
+    alias: REACT_ALIAS, outfile: out, logLevel: 'silent',
+  });
+  return import(pathToFileURL(out).href + (dev ? `?t=${Date.now()}` : ''));
+}
+
 export function routeId(file) {
   return createHash('sha1').update(file).digest('hex').slice(0, 10);
 }
@@ -119,6 +151,7 @@ export async function loadComponentRoute(pageFile, layouts, root, dev, force = f
     stdin: { contents: serverEntry(pageFile, layouts), resolveDir: path.dirname(pageFile), loader: 'js', sourcefile: 'glash-server-entry.js' },
     bundle: true, platform: 'node', format: 'esm', jsx: 'automatic', jsxImportSource: 'preact',
     external: ['preact', 'preact/*', 'preact-render-to-string'],
+    alias: REACT_ALIAS,
     outfile: out, logLevel: 'silent',
   });
   const mod = await import(pathToFileURL(out).href + (dev ? `?t=${Date.now()}` : ''));
@@ -135,6 +168,7 @@ export async function clientBundle(pageFile, layouts, dev) {
   const res = await eb.build({
     stdin: { contents: clientEntry(pageFile, layouts), resolveDir: path.dirname(pageFile), loader: 'jsx', sourcefile: 'glash-client-entry.jsx' },
     bundle: true, platform: 'browser', format: 'esm', minify: !dev, jsx: 'automatic', jsxImportSource: 'preact',
+    alias: REACT_ALIAS,
     write: false, logLevel: 'silent',
   });
   const js = res.outputFiles[0].text;

package/src/server/router.mjs

@@ -38,7 +38,8 @@ export async function discoverRoutes(routesDir) {
   const files = [];
   await walk(root, root, files);
   const routes = files
-    .filter((f) => /\.(mjs|js|jsx|tsx)$/.test(f.rel))
+    .filter((f) => /\.(mjs|js|jsx|tsx|ts)$/.test(f.rel))
+    .filter((f) => !/\.d\.ts$/.test(f.rel))
     // `_`-prefixed files are private (layouts, helpers) — not routes.
     .filter((f) => !f.rel.split('/').some((seg) => seg.startsWith('_')))
     .map((f) => toRoute(f.rel, f.file));
@@ -58,7 +59,7 @@ async function walk(root, dir, out) {
 }
 
 function toRoute(rel, file) {
-  const clean = rel.replace(/\.(mjs|js|jsx|tsx)$/, '');
+  const clean = rel.replace(/\.(mjs|js|jsx|tsx|ts)$/, '');
   const isApi = clean === 'api' || clean.startsWith('api/');
   const segs = [];
   for (const part of clean.split('/').filter(Boolean)) {

package/src/server/server.mjs

@@ -14,7 +14,7 @@ import { pathToFileURL } from 'node:url';
 import { discoverRoutes, matchRoute, findMiddleware } from './router.mjs';
 import { renderDocument, documentParts, renderMeta, escapeHtml } from './html.mjs';
 import { NAV_CLIENT } from './nav-client.mjs';
-import { isComponentRoute, loadComponentRoute, clientBundle, renderComponent, composeVNode, getPipeableRenderer, routeId, findLayouts, clearJsxCaches } from './jsx.mjs';
+import { isComponentRoute, loadComponentRoute, clientBundle, renderComponent, composeVNode, getPipeableRenderer, routeId, findLayouts, clearJsxCaches, compileModule } from './jsx.mjs';
 import { securityHeaders } from '../security/headers.mjs';
 import { loadConfig } from '../config.mjs';
 
@@ -83,7 +83,7 @@ export async function createGlashServer({ root = process.cwd(), dev = false } =
       const ctx = makeCtx(req, res, url, match.params);
       // Run the middleware chain (root -> leaf). Any return value short-circuits.
       for (const mwFile of findMiddleware(routesDir, match.route.file)) {
-        const mwMod = await importRoute(mwFile);
+        const mwMod = await compileModule(mwFile, root, dev);
         const mw = mwMod.default || mwMod.middleware;
         if (typeof mw !== 'function') continue;
         const result = await mw(ctx);
@@ -94,13 +94,13 @@ export async function createGlashServer({ root = process.cwd(), dev = false } =
         return send(res, 200, match.route.isApi ? 'application/json' : 'text/html; charset=utf-8', '', secHeaders);
       }
       if (match.route.isApi) {
-        const mod = await importRoute(match.route.file);
+        const mod = await compileModule(match.route.file, root, dev);
         return await handleApi(res, mod, req, ctx, secHeaders);
       }
       if (isComponentRoute(match.route.file)) {
         return await handleComponentPage(res, match.route, ctx, cfg, secHeaders, root, routesDir, dev);
       }
-      const mod = await importRoute(match.route.file);
+      const mod = await compileModule(match.route.file, root, dev);
       return await handlePage(res, mod, ctx, cfg, secHeaders, dev);
     } catch (err) {
       if (res.headersSent) return res.end(); // error mid-stream — can't replace headers