mintiljs 0.1.0

package/README.md

@@ -0,0 +1,192 @@
+# MintilJS
+
+> Minimal SSR web framework for Bun — React pages rendered on the server, zero client JavaScript unless you ask for it.
+
+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
+cd my-app
+bun run mintil dev
+```
+
+## Features
+
+- **File-based routing** — `pages/` → SSR routes, `api/` → JSON endpoints
+- **SSR by default** — zero JS in the browser unless you opt in
+- **`useClient`** — per-page hydration bundles via `Bun.build`
+- **Islands** — independent interactive components, no full-page re-render
+- **`getServerSideProps`** — per-request data fetching
+- **Hierarchical middleware** — global, API-wide, directory-scoped
+- **Layouts** — root layout (`components/layouts/base.tsx`) + per-directory overrides
+- **Tailwind v4** — automatic CSS processing via PostCSS
+- **Streaming SSR** — `renderToReadableStream` for pages without client bundles
+- **Auth module** — `mintiljs/auth` (JWT, sessions, middleware)
+- **i18n module** — `mintiljs/i18n` (auto-detected messages, placeholders, CSR fetcher)
+- **Plugin system** — extend the app at startup
+- **Auto-reload** — file watcher in development
+
+## Install
+
+```sh
+bun add mintiljs
+```
+
+## Quick Start
+
+```
+my-app/
+  pages/                → SSR routes
+    index.tsx             /
+    blog/
+      (:slug).tsx         /blog/:slug
+      layout.tsx          layout scoped to /blog/*
+  api/                  → JSON endpoints
+    hello.ts              /api/hello
+    middleware.ts         applies to all /api/*
+  islands/              → auto-registered hydratable components
+    Counter.tsx
+  components/
+    layouts/
+      base.tsx            root layout
+  i18n/                 → auto-detected messages
+    messages/
+      en/0.json
+      pt-BR.json
+  mintil.config.ts      → project config (optional)
+  middleware.ts         → root middleware (every request)
+```
+
+### Create a page
+
+```tsx
+// pages/index.tsx → /
+export default function Home() {
+  return <h1 className="text-3xl font-bold">Home</h1>;
+}
+```
+
+### Add an API endpoint
+
+```ts
+// api/hello.ts → GET /api/hello
+import type { ApiHandler } from "mintiljs";
+
+export default (c) => c.json({ message: "Hello" });
+```
+
+### Make a page interactive
+
+```tsx
+// pages/counter.tsx
+import React from "react";
+
+export const useClient = true;
+
+export default function Counter() {
+  const [count, setCount] = React.useState(0);
+  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
+}
+```
+
+### Fetch data on every request
+
+```tsx
+import type { GetServerSideProps } from "mintiljs";
+
+export const getServerSideProps: GetServerSideProps = async ({ params, searchParams }) => {
+  const data = await db.find(params.id);
+  return { props: { data } };
+};
+
+export default function Page({ data }: { data: any }) {
+  return <div>{data.name}</div>;
+}
+```
+
+## Configuration
+
+Export a `MintilConfig` default from `mintil.config.ts`:
+
+```ts
+import type { MintilConfig } from "mintiljs";
+
+export default {
+  port: 3456,
+  host: false,          // true = bind to 0.0.0.0
+  mode: "development",  // "development" | "production"
+  plugins: [],
+} satisfies MintilConfig;
+```
+
+## CLI
+
+| Command | Description |
+|---|---|
+| `mintil init <name>` | Scaffold a new project |
+| `mintil dev` | Dev mode with auto-reload |
+| `mintil start` | Production mode |
+| `mintil g page <n>` | Scaffold a page |
+| `mintil g api <n>` | Scaffold an API route |
+| `mintil g island <n>` | Scaffold an island |
+
+## Modules
+
+### Auth (`mintiljs/auth`)
+
+```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 token = await auth.signJWT({ sub: userId });
+const payload = await auth.verifyJWT(token);
+app.get("/api/admin", auth.requireAuth, handler);
+```
+
+### i18n (`mintiljs/i18n`)
+
+```
+i18n/messages/en/0.json   → { "greeting": "Hello" }
+i18n/messages/en/1.json   → { "welcome": "Welcome to {site}!" }
+i18n/messages/pt-BR.json  → { "greeting": "Olá" }
+```
+
+```ts
+import { getMessages, t, format } from "mintiljs/i18n";
+
+const msgs = await getMessages("en");
+t(msgs, "greeting")                              // "Hello"
+t(msgs, "welcome", { site: "MintilJS" })         // "Welcome to MintilJS!"
+format("Hello {name}!", { name: "John" })        // "Hello John!"
+```
+
+The framework auto-registers `/_mintil/i18n/:locale` for CSR usage.
+
+### Plugin System
+
+```ts
+import type { MintilPlugin } from "mintiljs";
+
+const health: MintilPlugin = {
+  name: "health",
+  setup(app) { app.get("/health", (c) => c.json({ ok: true })); },
+};
+
+export default { plugins: [health] } satisfies MintilConfig;
+```
+
+## API Reference
+
+Full TypeDoc-generated documentation at `docs/api/`:
+
+```sh
+bun run docs
+```
+
+## License
+
+MIT

package/auth/index.ts

@@ -0,0 +1 @@
+export * from "../src/auth/index.ts";

package/i18n/index.ts

@@ -0,0 +1 @@
+export * from "../src/i18n/index.ts";

package/index.ts

@@ -0,0 +1 @@
+export * from "./src/index.ts";

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "mintiljs",
+  "version": "0.1.0",
+  "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",
+  "main": "index.ts",
+  "types": "index.ts",
+  "exports": {
+    ".": "./index.ts",
+    "./auth": "./src/auth/index.ts",
+    "./i18n": "./src/i18n/index.ts"
+  },
+  "bin": {
+    "mintil": "./src/cli/cli.ts"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "templates",
+    "i18n",
+    "auth"
+  ],
+  "scripts": {
+    "dev": "bun run src/cli/cli.ts dev",
+    "start": "bun run src/cli/cli.ts start",
+    "mintil": "bun run src/cli/cli.ts",
+    "docs": "bun x typedoc --options typedoc.json"
+  },
+  "dependencies": {
+    "hono": "^4.12.25",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  },
+  "optionalDependencies": {
+    "@tailwindcss/postcss": "^4.3.1",
+    "postcss": "^8.5.15"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mozinova/mintiljs.git"
+  },
+  "homepage": "https://github.com/mozinova/mintiljs#readme",
+  "bugs": {
+    "url": "https://github.com/mozinova/mintiljs/issues"
+  },
+  "license": "MIT",
+  "author": "Daniel Mucamba",
+  "keywords": [
+    "ssr",
+    "react",
+    "bun",
+    "hono",
+    "framework",
+    "server-rendering",
+    "islands",
+    "i18n",
+    "authentication"
+  ]
+}

package/src/auth/index.ts

@@ -0,0 +1,5 @@
+export { InMemorySessionStore } from "./store.ts";
+export { signJWT, verifyJWT } from "./jwt.ts";
+export { createSession, getSession, updateSession, destroySession } from "./session.ts";
+export { createAuthMiddleware } from "./middleware.ts";
+export type { Session, SessionStore, JWTConfig, SessionConfig, AuthConfig } from "./types.ts";

package/src/auth/jwt.ts

@@ -0,0 +1,101 @@
+function base64urlEncode(buffer: ArrayBuffer): string {
+  const base64 = Buffer.from(buffer).toString("base64");
+  return base64.replace(/=/g, "").replace(/\+/g, "-").replace(/\//g, "_");
+}
+
+function base64urlDecode(str: string): Uint8Array {
+  const base64 = str.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = base64.padEnd(base64.length + (4 - (base64.length % 4)) % 4, "=");
+  return Buffer.from(padded, "base64");
+}
+
+function parseExpiresIn(value: string | number): number {
+  if (typeof value === "number") return value;
+  const match = value.match(/^(\d+)\s*(s|m|h|d|w)$/);
+  if (!match) return 3600;
+  const num = parseInt(match[1], 10);
+  switch (match[2]) {
+    case "s": return num;
+    case "m": return num * 60;
+    case "h": return num * 3600;
+    case "d": return num * 86400;
+    case "w": return num * 604800;
+    default: return 3600;
+  }
+}
+
+export async function signJWT(
+  payload: Record<string, any>,
+  secret: string,
+  options?: { expiresIn?: string | number; issuer?: string; audience?: string },
+): Promise<string> {
+  const header = { alg: "HS256", typ: "JWT" };
+  const now = Math.floor(Date.now() / 1000);
+  const tokenPayload: Record<string, any> = {
+    ...payload,
+    iat: now,
+  };
+
+  if (options?.expiresIn) {
+    tokenPayload.exp = now + parseExpiresIn(options.expiresIn);
+  }
+  if (options?.issuer) tokenPayload.iss = options.issuer;
+  if (options?.audience) tokenPayload.aud = options.audience;
+
+  const headerB64 = base64urlEncode(new TextEncoder().encode(JSON.stringify(header)));
+  const payloadB64 = base64urlEncode(new TextEncoder().encode(JSON.stringify(tokenPayload)));
+
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+
+  const signature = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    new TextEncoder().encode(`${headerB64}.${payloadB64}`),
+  );
+
+  return `${headerB64}.${payloadB64}.${base64urlEncode(signature)}`;
+}
+
+export async function verifyJWT(
+  token: string,
+  secret: string,
+  options?: { issuer?: string; audience?: string },
+): Promise<Record<string, any> | null> {
+  const parts = token.split(".");
+  if (parts.length !== 3) return null;
+
+  const [headerB64, payloadB64, signatureB64] = parts;
+
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["verify"],
+  );
+
+  const valid = await crypto.subtle.verify(
+    "HMAC",
+    key,
+    base64urlDecode(signatureB64),
+    new TextEncoder().encode(`${headerB64}.${payloadB64}`),
+  );
+
+  if (!valid) return null;
+
+  const payload = JSON.parse(new TextDecoder().decode(base64urlDecode(payloadB64)));
+
+  const now = Math.floor(Date.now() / 1000);
+  if (payload.exp && payload.exp < now) return null;
+
+  if (options?.issuer && payload.iss !== options.issuer) return null;
+  if (options?.audience && payload.aud !== options.audience) return null;
+
+  return payload;
+}

package/src/auth/middleware.ts

@@ -0,0 +1,150 @@
+import type { Context } from "hono";
+import { getCookie, setCookie, deleteCookie } from "hono/cookie";
+import { verifyJWT, signJWT } from "./jwt.ts";
+import { createSession, getSession, destroySession } from "./session.ts";
+import type { Session, SessionStore, JWTConfig } from "./types.ts";
+import type { ApiResponse } from "../types/api.ts";
+
+export function createAuthMiddleware(config: {
+  jwt: JWTConfig;
+  session: {
+    store: SessionStore;
+    maxAge: number;
+    cookieName: string;
+    cookiePath: string;
+  };
+}) {
+  const { jwt: jwtConfig, session: sessionConfig } = config;
+
+  async function getSessionFromCookie(c: Context): Promise<Session | null> {
+    const raw = getCookie(c, sessionConfig.cookieName);
+    if (!raw) return null;
+
+    const payload = await verifyJWT(raw, jwtConfig.secret);
+    if (!payload || !payload.sid) return null;
+
+    return getSession(sessionConfig.store, payload.sid as string);
+  }
+
+  async function setSessionCookie(c: Context, sid: string): Promise<void> {
+    const token = await signJWT(
+      { sid },
+      jwtConfig.secret,
+      { expiresIn: sessionConfig.maxAge },
+    );
+
+    setCookie(c, sessionConfig.cookieName, token, {
+      httpOnly: true,
+      secure: true,
+      sameSite: "Lax",
+      path: sessionConfig.cookiePath,
+      maxAge: sessionConfig.maxAge,
+    });
+  }
+
+  function clearSessionCookie(c: Context): void {
+    deleteCookie(c, sessionConfig.cookieName, { path: sessionConfig.cookiePath });
+  }
+
+  return {
+    signJWT: (payload: Record<string, any>) =>
+      signJWT(payload, jwtConfig.secret, {
+        expiresIn: jwtConfig.expiresIn,
+        issuer: jwtConfig.issuer,
+        audience: jwtConfig.audience,
+      }),
+    verifyJWT: (token: string) =>
+      verifyJWT(token, jwtConfig.secret, {
+        issuer: jwtConfig.issuer,
+        audience: jwtConfig.audience,
+      }),
+
+    sessionMiddleware: async (c: ApiResponse, next: () => Promise<void>) => {
+      const ctx = c as unknown as Context;
+      const session = await getSessionFromCookie(ctx);
+      if (session) {
+        c.set("session", session);
+        c.set("userId", session.userId);
+      }
+      await next();
+    },
+
+    requireAuth: async (c: ApiResponse, next: () => Promise<void>) => {
+      const authHeader = c.req.header("Authorization");
+      if (authHeader?.startsWith("Bearer ")) {
+        const token = authHeader.slice(7);
+        const payload = await verifyJWT(token, jwtConfig.secret, {
+          issuer: jwtConfig.issuer,
+          audience: jwtConfig.audience,
+        });
+        if (payload) {
+          c.set("user", payload);
+          c.set("userId", payload.sub || payload.userId);
+          await next();
+          return;
+        }
+      }
+
+      const ctx = c as unknown as Context;
+      const session = await getSessionFromCookie(ctx);
+      if (session) {
+        c.set("session", session);
+        c.set("userId", session.userId);
+        await next();
+        return;
+      }
+
+      c.status(401);
+      return c.json({ error: "Unauthorized" });
+    },
+
+    optionalAuth: async (c: ApiResponse, next: () => Promise<void>) => {
+      const authHeader = c.req.header("Authorization");
+      if (authHeader?.startsWith("Bearer ")) {
+        const token = authHeader.slice(7);
+        const payload = await verifyJWT(token, jwtConfig.secret, {
+          issuer: jwtConfig.issuer,
+          audience: jwtConfig.audience,
+        });
+        if (payload) {
+          c.set("user", payload);
+          c.set("userId", payload.sub || payload.userId);
+        }
+      } else {
+        const ctx = c as unknown as Context;
+        const session = await getSessionFromCookie(ctx);
+        if (session) {
+          c.set("session", session);
+          c.set("userId", session.userId);
+        }
+      }
+      await next();
+    },
+
+    login: async (
+      c: ApiResponse,
+      userId: string,
+      sessionData?: Record<string, any>,
+    ) => {
+      const sess = await createSession(
+        sessionConfig.store,
+        userId,
+        sessionData,
+        sessionConfig.maxAge,
+      );
+      await setSessionCookie(c as unknown as Context, sess.id);
+      return sess;
+    },
+
+    logout: async (c: ApiResponse) => {
+      const session = c.get("session") as Session | undefined;
+      if (session) {
+        await destroySession(sessionConfig.store, session.id);
+      }
+      clearSessionCookie(c as unknown as Context);
+    },
+
+    setSessionCookie,
+    clearSessionCookie,
+  };
+}

package/src/auth/session.ts

@@ -0,0 +1,46 @@
+import crypto from "node:crypto";
+import type { Session, SessionStore } from "./types.ts";
+
+export function createSessionId(): string {
+  return crypto.randomUUID();
+}
+
+export async function createSession(
+  store: SessionStore,
+  userId: string,
+  data: Record<string, any> = {},
+  maxAge: number = 7 * 24 * 3600,
+): Promise<Session> {
+  const now = new Date();
+  const session: Session = {
+    id: createSessionId(),
+    userId,
+    data,
+    createdAt: now,
+    expiresAt: new Date(now.getTime() + maxAge * 1000),
+  };
+  await store.create(session);
+  return session;
+}
+
+export async function getSession(
+  store: SessionStore,
+  sessionId: string,
+): Promise<Session | null> {
+  return store.get(sessionId);
+}
+
+export async function updateSession(
+  store: SessionStore,
+  sessionId: string,
+  data: Record<string, any>,
+): Promise<void> {
+  await store.update(sessionId, data);
+}
+
+export async function destroySession(
+  store: SessionStore,
+  sessionId: string,
+): Promise<void> {
+  await store.destroy(sessionId);
+}

package/src/auth/store.ts

@@ -0,0 +1,39 @@
+import type { Session, SessionStore } from "./types.ts";
+
+export class InMemorySessionStore implements SessionStore {
+  private sessions = new Map<string, Session>();
+
+  async create(session: Session): Promise<void> {
+    this.sessions.set(session.id, session);
+  }
+
+  async get(id: string): Promise<Session | null> {
+    const s = this.sessions.get(id);
+    if (!s) return null;
+    if (s.expiresAt < new Date()) {
+      this.sessions.delete(id);
+      return null;
+    }
+    return s;
+  }
+
+  async update(id: string, data: Record<string, any>): Promise<void> {
+    const session = this.sessions.get(id);
+    if (session) {
+      session.data = data;
+    }
+  }
+
+  async destroy(id: string): Promise<void> {
+    this.sessions.delete(id);
+  }
+
+  async cleanup(): Promise<void> {
+    const now = new Date();
+    for (const [id, session] of this.sessions) {
+      if (session.expiresAt < now) {
+        this.sessions.delete(id);
+      }
+    }
+  }
+}

package/src/auth/types.ts

@@ -0,0 +1,55 @@
+/** Represents an authenticated user session. */
+export interface Session {
+  /** Unique session identifier. */
+  id: string;
+  /** ID of the user this session belongs to. */
+  userId: string;
+  /** Arbitrary data stored with the session. */
+  data: Record<string, any>;
+  /** When the session was created. */
+  createdAt: Date;
+  /** When the session expires and should be considered invalid. */
+  expiresAt: Date;
+}
+
+/**
+ * Abstract interface for session persistence.
+ * Implement this to store sessions in Redis, SQLite, etc.
+ */
+export interface SessionStore {
+  create(session: Session): Promise<void>;
+  get(id: string): Promise<Session | null>;
+  update(id: string, data: Record<string, any>): Promise<void>;
+  destroy(id: string): Promise<void>;
+  cleanup?(): Promise<void>;
+}
+
+/** Configuration options for JWT signing and verification. */
+export interface JWTConfig {
+  /** HMAC-SHA256 secret key. Must be kept private. */
+  secret: string;
+  /** Token expiration duration (e.g. `"1h"`, `"7d"`, or seconds as number). */
+  expiresIn?: string | number;
+  /** Expected `iss` claim for verification. */
+  issuer?: string;
+  /** Expected `aud` claim for verification. */
+  audience?: string;
+}
+
+/** Configuration for cookie-based sessions. */
+export interface SessionConfig {
+  /** The session store implementation. */
+  store: SessionStore;
+  /** Session max age in seconds (default: 7 days). */
+  maxAge?: number;
+  /** Cookie name (default: `"mintil_session"`). */
+  cookieName?: string;
+  /** Cookie path (default: `"/"`). */
+  cookiePath?: string;
+}
+
+/** Complete configuration for the auth module. */
+export interface AuthConfig {
+  jwt: JWTConfig;
+  session?: SessionConfig;
+}