mintiljs 0.1.0

package/src/index.ts

@@ -0,0 +1,10 @@
+export { createMintilApp, start, resetStarted } from "./core/runtime.ts";
+export { resolveConfig } from "./core/config.ts";
+export { Island, registerIsland } from "./render/island.tsx";
+export type { IslandDef } from "./render/island.tsx";
+
+export type { MintilConfig, ResolvedConfig, MintilMode } from "./types/config.ts";
+export type { PageProps, PageComponent, GetServerSideProps, ServerSidePropsContext } from "./types/page.ts";
+export type { ApiRequest, ApiResponse, ApiHandler, ApiMethodHandler, MintilRequest, MintilResponse } from "./types/api.ts";
+export type { MintilMiddleware } from "./types/middleware.ts";
+export type { MintilPlugin } from "./types/plugin.ts";

package/src/render/island.tsx

@@ -0,0 +1,78 @@
+import React from "react";
+
+/** Registered island component definition. */
+export interface IslandDef {
+  /** The React component to render. */
+  component: React.ComponentType<any>;
+  /** Absolute path to the source file (used to build the client bundle). */
+  file: string;
+}
+
+const islandRegistry = new Map<string, IslandDef>();
+
+let usedIslands: string[] = [];
+const islandPropsMap = new Map<string, any>();
+
+/**
+ * Register an island component so it can be used via `<Island name="..." />`.
+ * Called automatically during startup for files inside the project's `islands/` directory.
+ */
+export function registerIsland(name: string, def: IslandDef) {
+  islandRegistry.set(name, def);
+}
+
+/** Retrieve a registered island definition by name. */
+export function getIslandDef(name: string): IslandDef | undefined {
+  return islandRegistry.get(name);
+}
+
+/** Clear the per-request island usage tracker. Called before each SSR render. */
+export function resetIslands() {
+  usedIslands = [];
+  islandPropsMap.clear();
+}
+
+/** Returns the list of island names used during the current render. */
+export function getUsedIslands(): string[] {
+  return usedIslands;
+}
+
+/** Returns the props passed to a given island during the current render. */
+export function getIslandProps(name: string): any {
+  return islandPropsMap.get(name);
+}
+
+/**
+ * Island component — renders a registered island on the server and marks it
+ * for client hydration.
+ *
+ * @example
+ * ```tsx
+ * import { Island } from "mintiljs";
+ *
+ * export default function Page() {
+ *   return <Island name="Counter" props={{ initial: 0 }} />;
+ * }
+ * ```
+ */
+export function Island({
+  name,
+  props = {},
+}: {
+  name: string;
+  props?: any;
+}) {
+  const def = islandRegistry.get(name);
+  if (!def) {
+    console.error(`[mintil] Island "${name}" not registered`);
+    return null;
+  }
+  if (!usedIslands.includes(name)) usedIslands.push(name);
+  islandPropsMap.set(name, props);
+
+  return React.createElement(
+    "div",
+    { "data-island": name, "data-props": JSON.stringify(props) },
+    React.createElement(def.component, props),
+  );
+}

package/src/render/ssr.tsx

@@ -0,0 +1,198 @@
+import React from "react";
+import { renderToString } from "react-dom/server";
+import path from "node:path";
+import { pathExists } from "../utils/fs.ts";
+import { processCss } from "../core/css.ts";
+import type { PageComponent } from "../types/page.ts";
+
+export interface RenderOptions {
+  root: string;
+  route: string;
+  params: Record<string, string>;
+  searchParams: URLSearchParams;
+  mode?: "development" | "production";
+  nonce?: string;
+  layout?: PageComponent;
+  clientBundle?: string;
+  frameworkUrl?: string;
+  extraProps?: Record<string, any>;
+  islandScripts?: string[];
+}
+
+function ErrorFallback({ error }: { error: Error }) {
+  return React.createElement(
+    "div",
+    {
+      style: {
+        padding: "2rem",
+        fontFamily: "system-ui, sans-serif",
+        maxWidth: "640px",
+        margin: "4rem auto",
+      },
+    },
+    React.createElement("h1", { style: { color: "#b91c1c" } }, "SSR Error"),
+    React.createElement(
+      "p",
+      { style: { color: "#6b7280" } },
+      "An error occurred while rendering this page on the server.",
+    ),
+    React.createElement(
+      "pre",
+      {
+        style: {
+          background: "#f3f4f6",
+          padding: "1rem",
+          borderRadius: "6px",
+          overflow: "auto",
+          fontSize: "0.875rem",
+        },
+      },
+      error.stack || error.message || String(error),
+    ),
+  );
+}
+
+function buildPageTree(
+  Page: PageComponent,
+  opts: RenderOptions,
+): React.ReactElement {
+  const pageProps = { params: opts.params, searchParams: opts.searchParams, ...opts.extraProps };
+  const pageElement = React.createElement(
+    "div",
+    { id: "__mintil-root" },
+    React.createElement(Page, pageProps),
+  );
+
+  if (opts.layout) {
+    return React.createElement(opts.layout, { children: pageElement });
+  }
+  return pageElement;
+}
+
+function buildHtmlShell(
+  content: string,
+  extra: string,
+  css: string,
+  route: string,
+): string {
+  const title = route === "/" ? "Mintil App" : `Mintil — ${route.slice(1)}`;
+
+  if (content.trim().toLowerCase().startsWith("<!doctype") || content.includes("<html")) {
+    return extra ? content.replace(/<\/body>/i, `${extra}</body>`) : content;
+  }
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>${title}</title>
+  <style>${css}</style>
+</head>
+<body>
+  ${content}
+  ${extra}
+</body>
+</html>`;
+}
+
+async function loadLayout(root: string, nonce?: string): Promise<React.FC<any> | null> {
+  const layoutPath = path.join(root, "components", "layouts", "base.tsx");
+  if (await pathExists(layoutPath)) {
+    try {
+      const mod: any = await import(nonce ? `${layoutPath}?t=${nonce}` : layoutPath);
+      return mod.default ?? mod.Base ?? null;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+function buildExtraScripts(
+  opts: RenderOptions,
+  pageProps: Record<string, any>,
+): string {
+  const debugScript =
+    opts.mode === "development"
+      ? `<script>console.log("[mintil] development mode");</script>`
+      : "";
+
+  const needsImportmap = !!(opts.clientBundle || opts.islandScripts?.length);
+
+  let extra = debugScript;
+
+  if (needsImportmap) {
+    const fw = opts.frameworkUrl ?? `https://esm.sh/react@${React.version}`;
+    const importMap = {
+      imports: {
+        react: fw,
+        "react-dom": fw,
+        "react-dom/client": fw,
+        "react/jsx-runtime": fw,
+        "react/jsx-dev-runtime": fw,
+      },
+    };
+    extra += `\n<script type="importmap">${JSON.stringify(importMap)}</script>`;
+
+    if (opts.islandScripts?.length) {
+      extra += "\n" + opts.islandScripts.join("\n");
+    }
+
+    if (opts.clientBundle) {
+      extra += `\n<script id="__PAGE_PROPS__" type="application/json">${JSON.stringify(pageProps)}</script>`;
+      extra += `\n<script type="module" src="${opts.clientBundle}"></script>`;
+    }
+  }
+
+  return extra.trim();
+}
+
+/**
+ * Render a page to an HTML string using synchronous SSR.
+ * Falls back to an error page if rendering throws.
+ */
+export async function renderPage(
+  Page: PageComponent,
+  opts: RenderOptions,
+): Promise<string> {
+  const pageProps = { params: opts.params, searchParams: opts.searchParams, ...opts.extraProps };
+
+  // Resolve layout if not provided
+  const layout = opts.layout ?? (await loadLayout(opts.root, opts.nonce));
+
+  // Build element tree
+  const pageElement = layout
+    ? React.createElement(layout, { children: buildInnerPage(Page, pageProps) })
+    : buildInnerPage(Page, pageProps);
+
+  const css = await processCss(opts.root, opts.mode);
+
+  // SSR with error boundary
+  let content: string;
+  try {
+    content = renderToString(pageElement);
+  } catch (err) {
+    const error = err instanceof Error ? err : new Error(String(err));
+    console.error(`[mintil] SSR error for ${opts.route}:`, error.message);
+
+    // Render error fallback
+    const fallback = renderToString(
+      layout
+        ? React.createElement(layout, { children: ErrorFallback({ error }) })
+        : ErrorFallback({ error }),
+    );
+    content = fallback;
+  }
+
+  const extra = buildExtraScripts(opts, pageProps);
+  return buildHtmlShell(content, extra, css, opts.route);
+}
+
+function buildInnerPage(Page: PageComponent, pageProps: Record<string, any>) {
+  return React.createElement(
+    "div",
+    { id: "__mintil-root" },
+    React.createElement(Page, pageProps),
+  );
+}

package/src/render/stream.tsx

@@ -0,0 +1,144 @@
+import React from "react";
+import { renderToReadableStream } from "react-dom/server";
+import path from "node:path";
+import { pathExists } from "../utils/fs.ts";
+import { processCss } from "../core/css.ts";
+import type { PageComponent } from "../types/page.ts";
+import type { RenderOptions } from "./ssr.tsx";
+
+const encoder = new TextEncoder();
+
+function buildHeadChunk(css: string, route: string): string {
+  const title = route === "/" ? "Mintil App" : `Mintil — ${route.slice(1)}`;
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>${title}</title>
+  <style>${css}</style>
+</head>
+<body>`;
+}
+
+function buildTailChunk(extra: string): string {
+  return `${extra}
+</body>
+</html>`;
+}
+
+/**
+ * Render a page using React 19's streaming SSR (`renderToReadableStream`).
+ *
+ * Falls back to the synchronous renderer if:
+ * - The page uses `useClient` (client bundle) — needs full HTML for hydration
+ * - An error occurs during stream creation
+ *
+ * @returns A `Response` with the streamed HTML, or `null` to signal fallback.
+ */
+export async function tryStreamPage(
+  Page: PageComponent,
+  opts: RenderOptions,
+): Promise<Response | null> {
+  // Skip streaming for useClient pages — they need exact HTML for hydration
+  if (opts.clientBundle) return null;
+
+  const pageProps = { params: opts.params, searchParams: opts.searchParams, ...opts.extraProps };
+
+  let Layout: React.FC<any> | null = opts.layout ?? null;
+  if (!Layout) {
+    const layoutPath = path.join(opts.root, "components", "layouts", "base.tsx");
+    if (await pathExists(layoutPath)) {
+      try {
+        const mod: any = await import(layoutPath);
+        Layout = mod.default ?? mod.Base ?? null;
+      } catch {
+        // ignore
+      }
+    }
+  }
+
+  const css = await processCss(opts.root, opts.mode);
+
+  // Build the React element tree
+  const pageElement = React.createElement(
+    "div",
+    { id: "__mintil-root" },
+    React.createElement(Page, pageProps),
+  );
+
+  const element = Layout
+    ? React.createElement(Layout, { children: pageElement })
+    : pageElement;
+
+  try {
+    const stream = await renderToReadableStream(element, {
+      bootstrapModules: opts.islandScripts?.length
+        ? opts.islandScripts.map((s) => {
+            const match = s.match(/src="([^"]+)"/);
+            return match ? match[1] : s;
+          })
+        : undefined,
+    });
+
+    const head = buildHeadChunk(css, opts.route);
+
+    const debugScript =
+      opts.mode === "development"
+        ? `<script>console.log("[mintil] development mode");</script>`
+        : "";
+
+    const needsImportmap = !!(opts.islandScripts?.length);
+    let extraScripts = debugScript;
+
+    if (needsImportmap) {
+      const fw = opts.frameworkUrl ?? `https://esm.sh/react@${React.version}`;
+      const importMap = {
+        imports: {
+          react: fw,
+          "react-dom": fw,
+          "react-dom/client": fw,
+          "react/jsx-runtime": fw,
+          "react/jsx-dev-runtime": fw,
+        },
+      };
+      extraScripts += `\n<script type="importmap">${JSON.stringify(importMap)}</script>`;
+    }
+
+    const tail = buildTailChunk(extraScripts.trim());
+
+    // Combine head + react stream + tail into a single readable stream
+    let headWritten = false;
+    let tailWritten = false;
+
+    const combined = new ReadableStream({
+      async pull(controller) {
+        if (!headWritten) {
+          controller.enqueue(encoder.encode(head));
+          headWritten = true;
+        }
+
+        const reader = stream.getReader();
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          if (value) controller.enqueue(value);
+        }
+
+        if (!tailWritten) {
+          controller.enqueue(encoder.encode(tail));
+          tailWritten = true;
+        }
+
+        controller.close();
+      },
+    });
+
+    return new Response(combined, {
+      headers: { "Content-Type": "text/html; charset=utf-8" },
+    });
+  } catch (err) {
+    console.error(`[mintil] stream SSR error for ${opts.route}:`, err);
+    return null;
+  }
+}

package/src/router/api.ts

@@ -0,0 +1,111 @@
+import path from "node:path"; // used in walkFiles via fileToRoutePath but path.basename explicit
+import { pathExists, walkFiles, fileToRoutePath } from "../utils/fs.ts";
+import { withNonce } from "./shared.ts";
+import type { ApiHandler, ApiMethodHandler } from "../types/api.ts";
+import type { MintilMiddleware } from "../types/middleware.ts";
+
+const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"] as const;
+
+export interface ApiHandlerEntry {
+  method: string;
+  handler: ApiHandler;
+}
+
+export interface ApiRoute {
+  file: string;
+  route: string;
+  handlers: ApiHandlerEntry[];
+}
+
+export interface ApiMiddleware {
+  file: string;
+  route: string;
+  middleware: MintilMiddleware;
+}
+
+export async function collectApiRoutes(root: string, nonce?: string): Promise<ApiRoute[]> {
+  const apiDir = path.join(root, "api");
+  if (!(await pathExists(apiDir))) return [];
+
+  const routes: ApiRoute[] = [];
+  for await (const file of walkFiles(apiDir)) {
+    const ext = path.extname(file);
+    if (!isTsLike(ext) && !isJsLike(ext)) continue;
+
+    // Skip middleware files – they are not API routes.
+    const nameWithoutExt = path.basename(file, ext);
+    if (nameWithoutExt === "middleware") continue;
+
+    const route = fileToRoutePath(file, root);
+    const mod = await import(withNonce(file, nonce));
+    const handlers: ApiHandlerEntry[] = [];
+
+    for (const method of HTTP_METHODS) {
+      const fn: ApiMethodHandler | undefined = mod[method];
+      if (typeof fn !== "function") continue;
+      handlers.push({ method, handler: wrapMethodHandler(fn) });
+    }
+
+    if (handlers.length === 0) {
+      const fallback = mod.default ?? mod.handler ?? null;
+      if (typeof fallback === "function") {
+        handlers.push({ method: "ALL", handler: fallback });
+      }
+    }
+
+    if (handlers.length > 0) {
+      routes.push({ file, route, handlers });
+    }
+  }
+
+  routes.sort((a, b) => sortRoute(a.route, b.route));
+  return routes;
+}
+
+export async function collectApiMiddlewares(root: string, nonce?: string): Promise<ApiMiddleware[]> {
+  const apiDir = path.join(root, "api");
+  if (!(await pathExists(apiDir))) return [];
+
+  const middlewares: ApiMiddleware[] = [];
+  for await (const file of walkFiles(apiDir)) {
+    const basename = path.basename(file).replace(path.extname(file), "");
+    if (basename !== "middleware") continue;
+    // The middleware's route is the directory it lives in, not including the filename.
+    const dir = path.dirname(file);
+    const route = fileToRoutePath(dir, root);
+    const mod: any = await import(withNonce(file, nonce));
+    const mw = mod.default ?? null;
+    if (typeof mw !== "function") continue;
+    middlewares.push({ file, route, middleware: mw });
+  }
+
+  // Most specific (deepest) middleware first.
+  middlewares.sort((a, b) => b.route.length - a.route.length);
+  return middlewares;
+}
+
+function wrapMethodHandler(fn: ApiMethodHandler): ApiHandler {
+  return async (c) => {
+    const result = await fn(c.req, c);
+    if (result instanceof Response) return result;
+    if (result !== undefined) return c.json(result);
+    return c.body(null);
+  };
+}
+
+function isJsLike(ext: string) {
+  return ext === ".ts" || ext === ".js";
+}
+function isTsLike(ext: string) {
+  return ext === ".ts" || ext === ".tsx" || ext === ".js" || ext === ".jsx";
+}
+
+function routeSpecificity(route: string): number {
+  if (route.includes("*")) return -1000;
+  if (route.includes(":")) return -100;
+  return route.split("/").length;
+}
+
+function sortRoute(a: string, b: string): number {
+  return routeSpecificity(b) - routeSpecificity(a);
+}

package/src/router/index.ts

@@ -0,0 +1,9 @@
+export { collectPageRoutes, collectPageLayouts } from "./pages.ts";
+export type { PageRoute, PageLayout } from "./pages.ts";
+
+export { collectApiRoutes, collectApiMiddlewares } from "./api.ts";
+export type { ApiRoute, ApiMiddleware, ApiHandlerEntry } from "./api.ts";
+
+export { loadRootMiddleware } from "./middleware.ts";
+
+export { withNonce } from "./shared.ts";

package/src/router/middleware.ts

@@ -0,0 +1,16 @@
+import path from "node:path";
+import { pathExists } from "../utils/fs.ts";
+import { withNonce } from "./shared.ts";
+import type { MintilMiddleware } from "../types/middleware.ts";
+
+export async function loadRootMiddleware(root: string, nonce?: string): Promise<MintilMiddleware | null> {
+  const candidates = ["middleware.ts", "middleware.tsx", "middleware.js", "middleware.jsx"];
+  for (const file of candidates) {
+    const full = path.join(root, file);
+    if (!(await pathExists(full))) continue;
+    const mod: any = await import(withNonce(full, nonce));
+    const middleware = mod.default ?? null;
+    if (typeof middleware === "function") return middleware;
+  }
+  return null;
+}

package/src/router/pages.ts

@@ -0,0 +1,97 @@
+import path from "node:path";
+import { pathExists, walkFiles, fileToRoutePath } from "../utils/fs.ts";
+import { withNonce } from "./shared.ts";
+import type { Context } from "hono";
+import type { PageComponent, PageProps, GetServerSideProps } from "../types/page.ts";
+
+export interface PageRoute {
+  file: string;
+  route: string;
+  mod: any;
+  component: PageComponent;
+  useClient: boolean;
+  getServerSideProps?: GetServerSideProps;
+}
+
+export interface PageLayout {
+  file: string;
+  scope: string;
+  component: PageComponent;
+}
+
+export async function collectPageRoutes(root: string, nonce?: string): Promise<PageRoute[]> {
+  const pagesDir = path.join(root, "pages");
+  if (!(await pathExists(pagesDir))) return [];
+
+  const routes: PageRoute[] = [];
+  for await (const file of walkFiles(pagesDir)) {
+    const ext = path.extname(file);
+    if (!isJsxLike(ext) && !isJsLike(ext)) continue;
+
+    const basename = path.basename(file, ext);
+    if (basename === "layout") continue;
+
+    const route = fileToRoutePath(file, pagesDir);
+    const mod = await import(withNonce(file, nonce));
+    const component = mod.default ?? mod.Page ?? null;
+    if (typeof component !== "function") continue;
+    const useClient = mod.useClient === true;
+    const getServerSideProps = typeof mod.getServerSideProps === "function" ? mod.getServerSideProps.bind(null) : undefined;
+    routes.push({ file, route, mod, component, useClient, getServerSideProps });
+  }
+
+  routes.sort((a, b) => sortRoute(a.route, b.route));
+  return routes;
+}
+
+export async function collectPageLayouts(root: string, nonce?: string): Promise<PageLayout[]> {
+  const pagesDir = path.join(root, "pages");
+  if (!(await pathExists(pagesDir))) return [];
+
+  const layouts: PageLayout[] = [];
+  for await (const file of walkFiles(pagesDir)) {
+    const ext = path.extname(file);
+    if (!isJsxLike(ext) && !isJsLike(ext)) continue;
+
+    const basename = path.basename(file, ext);
+    if (basename !== "layout") continue;
+
+    const scopeRoute = fileToRoutePath(file, pagesDir);
+    const scope = scopeRoute.replace(/\/layout$/i, "") || "/";
+    const mod = await import(withNonce(file, nonce));
+    const component = mod.default ?? mod.Layout ?? null;
+    if (typeof component !== "function") continue;
+    layouts.push({ file, scope, component });
+  }
+
+  layouts.sort((a, b) => b.scope.length - a.scope.length);
+  return layouts;
+}
+
+function isJsxLike(ext: string) {
+  return ext === ".tsx" || ext === ".jsx";
+}
+function isJsLike(ext: string) {
+  return ext === ".ts" || ext === ".js";
+}
+
+function routeSpecificity(route: string): number {
+  if (route.includes("*")) return -1000;
+  if (route.includes(":")) return -100;
+  return route.split("/").length;
+}
+
+function sortRoute(a: string, b: string): number {
+  return routeSpecificity(b) - routeSpecificity(a);
+}
+
+export function pagePropsFromContext(c: Context): PageProps {
+  const params: Record<string, string> = {};
+  for (const [key, value] of Object.entries(c.req.param())) {
+    params[key] = String(value ?? "");
+  }
+  return {
+    params,
+    searchParams: new URL(c.req.url).searchParams,
+  };
+}

package/src/router/shared.ts

@@ -0,0 +1,3 @@
+export function withNonce(file: string, nonce?: string): string {
+  return nonce ? `${file}?t=${nonce}` : file;
+}