mintiljs 0.1.0 → 0.1.1

package/README.md

@@ -5,8 +5,9 @@
 MintilJS is a full-stack framework built on **Bun**, **Hono**, and **React 19**. Drop files in `pages/` and they become SSR routes. Add `api/` files for JSON endpoints. Throw in `islands/` for partial hydration. All with zero configuration.
 
 ```sh
-bun create mintiljs my-app
+bun create mintil my-app
 cd my-app
+bun install
 bun run mintil dev
 ```
 
@@ -28,6 +29,15 @@ bun run mintil dev
 
 ## Install
 
+```sh
+bun create mintil my-app
+cd my-app
+bun install
+bun run mintil dev
+```
+
+Or add to an existing project:
+
 ```sh
 bun add mintiljs
 ```
@@ -113,8 +123,9 @@ import type { MintilConfig } from "mintiljs";
 
 export default {
   port: 3456,
-  host: false,          // true = bind to 0.0.0.0
-  mode: "development",  // "development" | "production"
+  host: false,            // true = bind to 0.0.0.0
+  mode: "development",    // "development" | "production"
+  assetsPath: "/assets",  // prefix for public/ files; "/" to serve at root
   plugins: [],
 } satisfies MintilConfig;
 ```
@@ -123,7 +134,7 @@ export default {
 
 | Command | Description |
 |---|---|
-| `mintil init <name>` | Scaffold a new project |
+| `mintil init <name>` | Scaffold a new project (use `.` for current dir) |
 | `mintil dev` | Dev mode with auto-reload |
 | `mintil start` | Production mode |
 | `mintil g page <n>` | Scaffold a page |
@@ -135,16 +146,49 @@ export default {
 ### Auth (`mintiljs/auth`)
 
 ```ts
+// api/login.ts
 import { createAuthMiddleware, InMemorySessionStore } from "mintiljs/auth";
 
-const auth = createAuthMiddleware({
-  jwt: { secret: process.env.JWT_SECRET!, expiresIn: "1h" },
-  session: { store: new InMemorySessionStore(), maxAge: 86400, cookieName: "session", cookiePath: "/" },
+const JWT_SECRET = process.env.JWT_SECRET || "dev-secret";
+const store = new InMemorySessionStore();
+
+export const auth = createAuthMiddleware({
+  jwt: { secret: JWT_SECRET, expiresIn: "1h" },
+  session: { store, maxAge: 86400, cookieName: "session", cookiePath: "/" },
 });
 
-const token = await auth.signJWT({ sub: userId });
-const payload = await auth.verifyJWT(token);
-app.get("/api/admin", auth.requireAuth, handler);
+// POST /api/login — sign JWT and return it
+import type { ApiMethodHandler } from "mintiljs";
+
+export const POST: ApiMethodHandler = async (request, response) => {
+  const { username, password } = await request.json();
+  if (username !== "admin" || password !== "123456") {
+    return response.json({ error: "Invalid credentials" }, 401);
+  }
+  const token = await auth.signJWT({ sub: username, userId: username, role: "admin" });
+  return response.json({ token });
+};
+```
+
+```ts
+// api/admin/middleware.ts — protect all /api/admin/* routes
+import { auth } from "../login";
+
+export default auth.requireAuth;
+```
+
+```ts
+// api/me.ts — use the verified token
+import type { ApiMethodHandler } from "mintiljs";
+import { auth } from "./login";
+
+export const GET: ApiMethodHandler = async (request, response) => {
+  const token = request.header("Authorization")?.slice(7);
+  const payload = token ? await auth.verifyJWT(token) : null;
+  return payload
+    ? response.json({ user: { id: payload.userId, name: payload.sub } })
+    : response.json({ error: "Unauthorized" }, 401);
+};
 ```
 
 ### i18n (`mintiljs/i18n`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mintiljs",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Minimal SSR web framework for Bun — React pages rendered on the server, zero client JS unless you ask for it",
   "type": "module",
   "module": "index.ts",

package/src/cli/cli.ts

@@ -38,13 +38,17 @@ function showHelp() {
   console.log(`Usage: mintil <command>
 
 Commands:
-  init <name>       Create a new Mintil project in the <name> directory
-  dev               Run the project in development mode (forces mode: development)
+  init <name>       Create a new Mintil project (use "." for current dir)
+  dev               Run the project in development mode
   start             Run the project (uses config mode or defaults to production)
   generate <t> <n>  Scaffold a page, api, component, or island (alias: g)
   help              Show this help message
 
-Run \`mintil generate help\` for scaffold type options.
+Quick start:
+  bun create mintil my-app
+  cd my-app
+  bun install
+  bun run mintil dev
 `);
 }
 
@@ -54,15 +58,18 @@ async function initProject(name?: string) {
     process.exit(1);
   }
 
-  const target = path.resolve(process.cwd(), name);
+  const useCwd = name === ".";
+  const target = useCwd ? process.cwd() : path.resolve(process.cwd(), name);
   const template = path.resolve(import.meta.dir, "..", "..", "templates", "default");
 
   try {
     await fs.access(target);
-    console.error(`Directory already exists: ${target}`);
-    process.exit(1);
+    if (!useCwd) {
+      console.error(`Directory already exists: ${target}`);
+      process.exit(1);
+    }
   } catch {
-    // expected: directory does not exist
+    // expected: directory does not exist (unless useCwd)
   }
 
   await fs.cp(template, target, { recursive: true });
@@ -71,14 +78,16 @@ async function initProject(name?: string) {
   const pkgPath = path.join(target, "package.json");
   try {
     const pkg = JSON.parse(await fs.readFile(pkgPath, "utf-8")) as Record<string, unknown>;
-    pkg.name = name;
+    pkg.name = path.basename(target);
     await fs.writeFile(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
   } catch {
     // ignore if no package.json
   }
 
   console.log(`Created Mintil project at ${target}`);
-  console.log(`\nNext steps:\n  cd ${name}\n  bun install\n  mintil dev`);
+  console.log(`\nNext steps:`);
+  if (!useCwd) console.log(`  cd ${name}`);
+  console.log(`  bun install\n  mintil dev`);
 }
 
 async function runProject(command: "dev" | "start") {

package/src/core/config.ts

@@ -5,12 +5,15 @@ export function resolveConfig(root: string, userConfig?: MintilConfig): Resolved
   const envPort = process.env.PORT ? Number(process.env.PORT) : undefined;
   const envMode = process.env.NODE_ENV === "production" ? "production" : "development";
 
+  const assetsPath = userConfig?.assetsPath ?? "/";
+
   return {
     root,
     port: userConfig?.port ?? envPort ?? 3456,
     hosts: userConfig?.hosts ?? [],
     mode: userConfig?.mode ?? (envMode as ResolvedConfig["mode"]),
     host: userConfig?.host ?? false,
+    assetsPath: assetsPath.startsWith("/") ? assetsPath : `/${assetsPath}`,
     plugins: userConfig?.plugins ?? [],
   };
 }

package/src/core/routes.ts

@@ -2,7 +2,7 @@ import path from "node:path";
 import React from "react";
 import type { Hono } from "hono";
 import type { Context } from "hono";
-import { renderPage } from "../render/ssr.tsx";
+import { renderPage, renderClientShell } from "../render/ssr.tsx";
 import { tryStreamPage } from "../render/stream.tsx";
 import { resetIslands, getUsedIslands, getIslandDef } from "../render/island.tsx";
 import {
@@ -125,7 +125,7 @@ export async function registerPageRoutes(
 
     let clientBundle: string | null = null;
     let clientBundleName: string | null = null;
-    if (page.useClient && frameworkJs) {
+    if (page.useClient && !page.useServer && frameworkJs) {
       const js = await buildClientBundle(page.file, page.route, { mode: resolved.mode });
       if (js) {
         const bundleName = routeToBundleName(page.route);
@@ -152,7 +152,7 @@ export async function registerPageRoutes(
       const props = pagePropsFromContext(c);
 
       let extraProps: Record<string, any> | undefined;
-      if (page.getServerSideProps) {
+      if (page.getServerSideProps && !page.useServer) {
         try {
           const result = await page.getServerSideProps({
             params: props.params,
@@ -180,9 +180,27 @@ export async function registerPageRoutes(
         extraProps,
       };
 
+      if (page.useClient && clientBundle) {
+        // useClient pages skip SSR of the React tree (hooks like useState
+        // don't work server-side). Render just the layout shell with an
+        // empty root div — the client bundle hydrates the full component.
+        const html = await renderClientShell(pageOpts);
+        return c.html(html);
+      }
+
+      if (page.useServer) {
+        // useServer pages are async-first — skip island detection,
+        // skip getServerSideProps (component fetches its own data),
+        // go straight to streaming (supports Suspense/async components).
+        const streamResponse = await tryStreamPage(page.component, pageOpts);
+        if (streamResponse) return streamResponse;
+        // Fallback to sync render (will show error boundary if async)
+        const html = await renderPage(page.component, pageOpts);
+        return c.html(html);
+      }
+
       // Quick sync pass to detect used islands
       resetIslands();
-      const React = await import("react");
       const { renderToString } = await import("react-dom/server");
       const quickElement = buildQuickElement(page.component, pageOpts, layout);
       try { renderToString(quickElement); } catch {}

package/src/core/runtime.ts

@@ -34,19 +34,24 @@ export async function createMintilApp(
     return c.text(css, 200, { "Content-Type": "text/css" });
   });
 
-  app.get("/assets/*", async (c) => {
-    const subpath = c.req.path.replace(/^\/assets\//, "");
+  // Serve static files from public/ — works as a pass-through middleware so
+  // page/API routes still resolve when the file doesn't exist.
+  const prefix = resolved.assetsPath === "/" ? "" : resolved.assetsPath.replace(/\/+$/, "");
+  app.use("*", async (c, next) => {
+    if (c.req.method !== "GET") return next();
+    const reqPath = c.req.path;
+    // Skip internal routes
+    if (reqPath.startsWith("/_mintil") || reqPath === "/styles.css") return next();
+    // If a prefix is configured, only handle paths under it
+    if (prefix && !reqPath.startsWith(prefix)) return next();
+    const subpath = prefix ? reqPath.slice(prefix.length).replace(/^\//, "") : reqPath.replace(/^\//, "");
     const filePath = path.join(resolved.root, "public", subpath);
-    if (!filePath.startsWith(path.join(resolved.root, "public"))) {
-      return c.notFound();
-    }
+    if (!filePath.startsWith(path.join(resolved.root, "public"))) return next();
     try {
       const file = Bun.file(filePath);
-      if (!(await file.exists())) return c.notFound();
-      return new Response(file);
-    } catch {
-      return c.notFound();
-    }
+      if (await file.exists()) return new Response(file);
+    } catch { /* fall through */ }
+    return next();
   });
 
   // Auto-register i18n API if i18n/messages directory exists
@@ -129,3 +134,7 @@ export async function start(config?: MintilConfig): Promise<ReturnType<typeof Bu
 export function resetStarted() {
   started = false;
 }
+
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/src/render/ssr.tsx

@@ -196,3 +196,42 @@ function buildInnerPage(Page: PageComponent, pageProps: Record<string, any>) {
     React.createElement(Page, pageProps),
   );
 }
+
+function buildEmptyShell() {
+  return React.createElement("div", { id: "__mintil-root" });
+}
+
+/**
+ * Render a shell HTML for `useClient` pages — wraps the layout around an
+ * empty root div, then lets the client bundle hydrate the full component.
+ * Avoids SSR errors from hooks (useState, useEffect, etc.) that require
+ * a client-side React dispatcher.
+ */
+export async function renderClientShell(
+  opts: RenderOptions,
+): Promise<string> {
+  const pageProps = { params: opts.params, searchParams: opts.searchParams, ...opts.extraProps };
+
+  const layout = opts.layout ?? (await loadLayout(opts.root, opts.nonce));
+  const css = await processCss(opts.root, opts.mode);
+
+  let content: string;
+  try {
+    const pageElement = layout
+      ? React.createElement(layout, { children: buildEmptyShell() })
+      : buildEmptyShell();
+    content = renderToString(pageElement);
+  } catch (err) {
+    const error = err instanceof Error ? err : new Error(String(err));
+    console.error(`[mintil] client-shell render error for ${opts.route}:`, error.message);
+    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);
+}

package/src/router/pages.ts

@@ -10,6 +10,7 @@ export interface PageRoute {
   mod: any;
   component: PageComponent;
   useClient: boolean;
+  useServer: boolean;
   getServerSideProps?: GetServerSideProps;
 }
 
@@ -36,8 +37,9 @@ export async function collectPageRoutes(root: string, nonce?: string): Promise<P
     const component = mod.default ?? mod.Page ?? null;
     if (typeof component !== "function") continue;
     const useClient = mod.useClient === true;
+    const useServer = mod.useServer === true;
     const getServerSideProps = typeof mod.getServerSideProps === "function" ? mod.getServerSideProps.bind(null) : undefined;
-    routes.push({ file, route, mod, component, useClient, getServerSideProps });
+    routes.push({ file, route, mod, component, useClient, useServer, getServerSideProps });
   }
 
   routes.sort((a, b) => sortRoute(a.route, b.route));

package/src/types/config.ts

@@ -18,6 +18,8 @@ export interface MintilConfig {
   mode?: "development" | "production";
   /** Whether to bind to all interfaces (`0.0.0.0`). Defaults to `false` (loopback only). */
   host?: boolean;
+  /** URL path prefix for static assets from `public/`. Defaults to `/assets`. Set to `"/"` to serve at root. */
+  assetsPath?: string;
   /** Plugins to register. Each plugin's `setup` receives the Hono app and resolved config. */
   plugins?: import("./plugin.ts").MintilPlugin[];
 }

package/src/types/page.ts

@@ -17,8 +17,11 @@ export interface PageProps {
 /**
  * A page component. Must be the default export of a file inside `pages/`.
  * Receives {@link PageProps} (plus any extra props from `getServerSideProps`).
+ *
+ * When `useServer` is `true`, the component can be `async` and fetch data directly
+ * without `getServerSideProps`. React 19's streaming SSR handles Suspense natively.
  */
-export type PageComponent = (props: any) => import("react").JSX.Element;
+export type PageComponent = (props: any) => import("react").JSX.Element | Promise<import("react").JSX.Element>;
 
 /**
  * Context object passed to `getServerSideProps`.

package/templates/default/api/counter.ts

@@ -0,0 +1,10 @@
+import type { ApiHandler } from "mintiljs";
+
+const counter: ApiHandler = (c) => {
+  const count = parseInt(c.req.query("count") ?? "0", 10);
+  const action = c.req.query("action") ?? "inc";
+  const next = action === "inc" ? count + 1 : Math.max(0, count - 1);
+  return c.json({ count: next });
+};
+
+export default counter;

package/templates/default/api/middleware.ts

@@ -0,0 +1,8 @@
+import type { MintilMiddleware } from "mintiljs";
+
+const middleware: MintilMiddleware = async (c, next) => {
+  c.res.headers.set("X-API-Time", Date.now().toString());
+  await next();
+};
+
+export default middleware;

package/templates/default/components/layouts/base.tsx

@@ -14,6 +14,12 @@ export default function BaseLayout({ children }: { children: React.ReactNode })
           <nav className="mx-auto flex max-w-4xl items-center gap-6 px-4 py-4">
             <a href="/" className="text-sm font-medium text-blue-600 hover:text-blue-800">Home</a>
             <a href="/about" className="text-sm font-medium text-blue-600 hover:text-blue-800">About</a>
+            <a href="/counter" className="text-sm font-medium text-blue-600 hover:text-blue-800">Counter</a>
+            <a href="/ssr-counter" className="text-sm font-medium text-blue-600 hover:text-blue-800">SSR</a>
+            <a href="/island-demo" className="text-sm font-medium text-blue-600 hover:text-blue-800">Islands</a>
+            <a href="/server-data" className="text-sm font-medium text-blue-600 hover:text-blue-800">Server</a>
+            <a href="/blog" className="text-sm font-medium text-blue-600 hover:text-blue-800">Blog</a>
+            <a href="/i18n-test" className="text-sm font-medium text-blue-600 hover:text-blue-800">i18n</a>
           </nav>
         </header>
         <main className="mx-auto w-full max-w-4xl flex-1 px-4 py-10">{children}</main>

package/templates/default/i18n/messages/en.json

@@ -0,0 +1,12 @@
+{
+  "greeting": "Hello",
+  "nav.home": "Home",
+  "nav.about": "About",
+  "nav.counter": "Counter",
+  "nav.ssr": "SSR Counter",
+  "nav.i18n": "i18n",
+  "nav.blog": "Blog",
+  "welcome": "Welcome to {site}!",
+  "farewell": "Goodbye",
+  "builtWith": "Built with MintilJs"
+}

package/templates/default/islands/Counter.tsx

@@ -0,0 +1,34 @@
+import React from "react";
+
+interface CounterProps {
+  initial?: number;
+}
+
+export default function Counter({ initial = 0 }: CounterProps) {
+  const [count, setCount] = React.useState(initial);
+  return (
+    <div className="flex items-center gap-4">
+      <button
+        onClick={() => setCount((c) => c - 1)}
+        className="rounded-lg bg-gray-200 px-4 py-2 text-lg font-semibold hover:bg-gray-300"
+      >
+        -1
+      </button>
+      <span className="min-w-[3rem] text-center text-2xl font-mono font-bold tabular-nums">
+        {count}
+      </span>
+      <button
+        onClick={() => setCount((c) => c + 1)}
+        className="rounded-lg bg-blue-600 px-4 py-2 text-lg font-semibold text-white hover:bg-blue-700"
+      >
+        +1
+      </button>
+      <button
+        onClick={() => setCount(0)}
+        className="text-sm text-gray-500 underline hover:text-gray-700"
+      >
+        reset
+      </button>
+    </div>
+  );
+}

package/templates/default/middleware.ts

@@ -0,0 +1,8 @@
+import type { MintilMiddleware } from "mintiljs";
+
+const middleware: MintilMiddleware = async (c, next) => {
+  console.log(`[middleware] ${c.req.method} ${c.req.path}`);
+  await next();
+};
+
+export default middleware;

package/templates/default/package.json

@@ -1,6 +1,5 @@
 {
   "name": "my-mintil-app",
-  "module": "index.ts",
   "type": "module",
   "scripts": {
     "dev": "mintil dev",
@@ -9,9 +8,11 @@
   "peerDependencies": {
     "typescript": "^5"
   },
-  "dependencies": {
-    "mintiljs": "*",
+  "optionalDependencies": {
     "postcss": "^8",
     "@tailwindcss/postcss": "^4"
+  },
+  "dependencies": {
+    "mintiljs": "*"
   }
 }

package/templates/default/pages/about.tsx

@@ -8,6 +8,18 @@ export default function AboutPage() {
         MintilJs is a minimal SSR framework that runs on Bun. Pages are rendered with React on the server
         and streamed as HTML — no client-side JavaScript required.
       </p>
+      <div className="mt-8 space-y-4">
+        <h2 className="text-xl font-semibold">Features</h2>
+        <ul className="list-disc pl-6 space-y-2 text-gray-600">
+          <li>File-based routing — <code className="rounded bg-gray-100 px-1.5 py-0.5 text-sm font-mono text-blue-700">pages/</code> for SSR, <code className="rounded bg-gray-100 px-1.5 py-0.5 text-sm font-mono text-blue-700">api/</code> for JSON</li>
+          <li>Zero JS in browser unless you opt in with <code className="rounded bg-gray-100 px-1.5 py-0.5 text-sm font-mono text-blue-700">useClient</code></li>
+          <li>Islands — independent interactive components <code className="rounded bg-gray-100 px-1.5 py-0.5 text-sm font-mono text-blue-700">islands/</code></li>
+          <li>Internationalization via <code className="rounded bg-gray-100 px-1.5 py-0.5 text-sm font-mono text-blue-700">mintiljs/i18n</code></li>
+          <li>Auth module via <code className="rounded bg-gray-100 px-1.5 py-0.5 text-sm font-mono text-blue-700">mintiljs/auth</code></li>
+          <li>Hierarchical middleware — global, API, scoped</li>
+          <li>Tailwind v4 via PostCSS</li>
+        </ul>
+      </div>
     </section>
   );
 }

package/templates/default/pages/blog/index.tsx

@@ -0,0 +1,28 @@
+import React from "react";
+
+const posts = [
+  { slug: "hello-world", title: "Hello World" },
+  { slug: "getting-started", title: "Getting Started with MintilJS" },
+  { slug: "ssr-vs-csr", title: "SSR vs CSR" },
+];
+
+export default function BlogIndex() {
+  return (
+    <div>
+      <h1 className="mb-6 text-3xl font-bold tracking-tight">Blog</h1>
+      <ul className="space-y-4">
+        {posts.map((post) => (
+          <li key={post.slug}>
+            <a
+              href={`/blog/${post.slug}`}
+              className="block rounded-lg border border-gray-200 bg-white p-4 transition hover:border-blue-300 hover:shadow-sm"
+            >
+              <h2 className="text-lg font-semibold text-blue-600">{post.title}</h2>
+              <p className="mt-1 text-sm text-gray-500">/{post.slug}</p>
+            </a>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}

package/templates/default/pages/blog/layout.tsx

@@ -0,0 +1,12 @@
+import React from "react";
+
+export default function BlogLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="mx-auto max-w-2xl">
+      <nav className="mb-8 flex items-center gap-4 text-sm text-gray-500">
+        <a href="/blog" className="font-medium text-blue-600 hover:text-blue-800">All Posts</a>
+      </nav>
+      {children}
+    </div>
+  );
+}

package/templates/default/pages/i18n-test.tsx

@@ -0,0 +1,26 @@
+import React from "react";
+import { getMessages, t, format } from "mintiljs/i18n";
+import type { GetServerSideProps } from "mintiljs";
+
+export const getServerSideProps: GetServerSideProps = async (ctx) => {
+  const locale = (ctx.searchParams?.lang as string) || "en";
+  const messages = await getMessages(locale);
+  return { props: { locale, messages } };
+};
+
+export default function I18nPage({ locale, messages }: { locale: string; messages: Record<string, string> }) {
+  return (
+    <div>
+      <h1 className="mb-6 text-3xl font-bold tracking-tight">i18n Example</h1>
+      <p className="mb-2 text-gray-600">Locale: <code className="rounded bg-gray-100 px-1.5 py-0.5 text-sm font-mono text-blue-700">{locale}</code></p>
+      <div className="mt-6 space-y-2 rounded-lg border border-gray-200 bg-white p-6">
+        <p><strong>greeting:</strong> {t(messages, "greeting")}</p>
+        <p><strong>nav.home:</strong> {t(messages, "nav.home")}</p>
+        <p><strong>welcome:</strong> {t(messages, "welcome", { site: "MintilJS" })}</p>
+        <p><strong>format() example:</strong> {format("Welcome to {site}, {user}!", { site: "MintilJS", user: "dev" })}</p>
+        <p className="text-sm text-gray-500">Total messages: {Object.keys(messages).length}</p>
+      </div>
+      <p className="mt-4 text-sm text-gray-400">Try: <code>?lang=pt-BR</code></p>
+    </div>
+  );
+}

package/templates/default/pages/index.tsx

@@ -1,6 +1,16 @@
 import React from "react";
 import Card from "@app/components/card";
 
+const features = [
+  { href: "/about", title: "About", desc: "Learn more about MintilJS" },
+  { href: "/counter", title: "Counter (useClient)", desc: "Interactive page with client-side JavaScript" },
+  { href: "/ssr-counter", title: "SSR Counter", desc: "Server-rendered form-based interaction, zero JS" },
+  { href: "/island-demo", title: "Islands", desc: "Hydratable interactive components" },
+  { href: "/server-data", title: "Server (useServer)", desc: "Async component fetching data directly — zero JS" },
+  { href: "/blog", title: "Blog", desc: "Dynamic routes with (:slug).tsx" },
+  { href: "/i18n-test", title: "i18n", desc: "Internationalization with getMessages and t()" },
+];
+
 export default function HomePage() {
   return (
     <div>
@@ -9,6 +19,18 @@ export default function HomePage() {
       <Card title="Server rendered">
         This component was imported via <code className="rounded bg-gray-100 px-1.5 py-0.5 text-sm font-mono text-blue-700">@app/components/card</code>.
       </Card>
+      <div className="mt-8 grid gap-4 sm:grid-cols-2">
+        {features.map((f) => (
+          <a
+            key={f.href}
+            href={f.href}
+            className="rounded-lg border border-gray-200 bg-white p-4 transition hover:border-blue-300 hover:shadow-sm"
+          >
+            <h3 className="font-semibold text-blue-600">{f.title}</h3>
+            <p className="mt-1 text-sm text-gray-500">{f.desc}</p>
+          </a>
+        ))}
+      </div>
     </div>
   );
 }

package/templates/default/pages/island-demo.tsx

@@ -0,0 +1,14 @@
+import React from "react";
+import { Island } from "mintiljs";
+
+export default function IslandDemo() {
+  return (
+    <div>
+      <h1 className="mb-6 text-3xl font-bold tracking-tight">Island Demo</h1>
+      <p className="mb-4 text-gray-600">This counter is an Island — it hydrates independently on the client.</p>
+      <div className="rounded-lg border border-gray-200 bg-white p-6">
+        <Island name="Counter" props={{ initial: 42 }} />
+      </div>
+    </div>
+  );
+}

package/templates/default/pages/server-data.tsx

@@ -0,0 +1,36 @@
+import React from "react";
+
+export const useServer = true;
+
+async function fetchPosts() {
+  // Simula fetching de dados — podia ser DB, FS, API externa
+  return [
+    { id: 1, title: "MintilJS is fast" },
+    { id: 2, title: "SSR sem JavaScript" },
+    { id: 3, title: "React Server Components sem compilador" },
+  ];
+}
+
+export default async function ServerDataPage() {
+  const posts = await fetchPosts();
+
+  return (
+    <div>
+      <h1 className="mb-6 text-3xl font-bold tracking-tight">Server Data (useServer)</h1>
+      <p className="mb-4 text-gray-600">
+        Esta página usa <code className="rounded bg-gray-100 px-1.5 py-0.5 text-sm font-mono text-blue-700">useServer = true</code>.
+        O componente é <code className="rounded bg-gray-100 px-1.5 py-0.5 text-sm font-mono text-blue-700">async</code> e faz fetch
+        diretamente no servidor — sem <code className="rounded bg-gray-100 px-1.5 py-0.5 text-sm font-mono text-blue-700">getServerSideProps</code>.
+        Zero JavaScript enviado ao cliente.
+      </p>
+      <div className="space-y-3">
+        {posts.map((post) => (
+          <div key={post.id} className="rounded-lg border border-gray-200 bg-white p-4">
+            <h2 className="font-semibold text-gray-900">{post.title}</h2>
+            <p className="text-sm text-gray-500">Post #{post.id}</p>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}

package/templates/default/pages/ssr-counter.tsx

@@ -0,0 +1,19 @@
+import React from "react";
+
+export default function SsrCounterPage() {
+  return (
+    <div>
+      <h1 className="mb-6 text-3xl font-bold tracking-tight">SSR Counter</h1>
+      <p className="mb-4 text-gray-600">This counter uses a form POST — no client JavaScript needed.</p>
+      <form method="POST" action="/api/counter" className="flex items-center gap-4">
+        <span className="text-2xl font-mono font-bold tabular-nums">0</span>
+        <button type="submit" name="action" value="inc" className="rounded-lg bg-blue-600 px-4 py-2 text-white hover:bg-blue-700">
+          +1
+        </button>
+        <button type="submit" name="action" value="dec" className="rounded-lg bg-gray-200 px-4 py-2 hover:bg-gray-300">
+          -1
+        </button>
+      </form>
+    </div>
+  );
+}

package/templates/default/public/readme.txt

@@ -1 +1 @@
-This is a static asset served under /assets/readme.txt.
+This is a static asset served from the public/ directory.