mintiljs 0.1.0

package/src/types/api.ts

@@ -0,0 +1,106 @@
+/**
+ * Request object passed to API handlers and middlewares.
+ * Provides access to the incoming HTTP request data.
+ */
+export interface ApiRequest {
+  /** HTTP method (GET, POST, PUT, etc.). */
+  readonly method: string;
+  /** Full request URL as a string. */
+  readonly url: string;
+  /** URL pathname. */
+  readonly path: string;
+  /** The raw `Request` object. */
+  readonly raw: Request;
+  /** Get a path parameter by name, or all params as an object. */
+  param(key?: string): any;
+  /** Get a query string value by name, or all params as an object. */
+  query(key?: string): any;
+  /** Get a request header by name, or all headers as an object. */
+  header(name?: string): any;
+  /** Parse the request body as JSON. */
+  json<T = any>(): Promise<T>;
+  /** Parse the request body as text. */
+  text(): Promise<string>;
+  /** Parse the request body as FormData. */
+  formData(): Promise<FormData>;
+}
+
+/**
+ * Response object passed to API handlers and middlewares.
+ * Used to construct and send HTTP responses.
+ */
+export interface ApiResponse {
+  /** The incoming request. */
+  readonly req: ApiRequest;
+  /** The response object being built. */
+  readonly res: Response;
+  /** Set the HTTP response status code. */
+  status(code: number): void;
+  /** Set a response header. */
+  header(name: string, value: string): void;
+  /** Set a context-scoped variable (available to downstream handlers/middleware). */
+  set(key: string, value: any): void;
+  /** Get a context-scoped variable. */
+  get(key: string): any;
+  /** Map of context-scoped variables. */
+  var: Record<string, any>;
+  /** Send a JSON response. */
+  json(data: any, status?: number, headers?: Record<string, string | string[]>): Response;
+  /** Send a text response. */
+  text(data: string, status?: number, headers?: Record<string, string | string[]>): Response;
+  /** Send an HTML response. */
+  html(data: string, status?: number, headers?: Record<string, string | string[]>): Response;
+  /** Send a raw body response. */
+  body(data: any, status?: number, headers?: Record<string, string | string[]>): Response;
+  /** Redirect to another URL (default 302). */
+  redirect(location: string, status?: number): Response;
+  /** Create a new Response object. */
+  newResponse(data: any, status?: number, headers?: Record<string, string | string[]>): Response;
+  /** Return a 404 Not Found response. */
+  notFound(): Response;
+}
+
+/**
+ * Generic API handler that receives the full `ApiResponse`.
+ * Useful for catch-all handlers or when you need direct access to `c`.
+ *
+ * @example
+ * ```ts
+ * import type { ApiHandler } from "mintiljs";
+ *
+ * const handler: ApiHandler = (c) => {
+ *   return c.json({ ok: true });
+ * };
+ * export default handler;
+ * ```
+ */
+export type ApiHandler = (c: ApiResponse) => Response | Promise<Response> | unknown | Promise<unknown>;
+
+/**
+ * @deprecated Use `ApiRequest` instead.
+ */
+export type MintilRequest = ApiRequest;
+
+/**
+ * @deprecated Use `ApiResponse` instead.
+ */
+export type MintilResponse = ApiResponse;
+
+/**
+ * Named-method API handler.
+ *
+ * Export a function with this type from a file in `api/` to handle a specific HTTP method.
+ *
+ * @example
+ * ```ts
+ * import type { ApiMethodHandler } from "mintiljs";
+ *
+ * export const GET: ApiMethodHandler = (request, response) => {
+ *   return response.json({ ok: true });
+ * };
+ * ```
+ */
+export type ApiMethodHandler = (
+  request: ApiRequest,
+  response: ApiResponse,
+) => Response | Promise<Response> | unknown | Promise<unknown>;

package/src/types/config.ts

@@ -0,0 +1,35 @@
+/**
+ * User-facing configuration for a MintilJS project.
+ * Export a default object of this type from your project's entry file (`mintil.config.ts`).
+ */
+export interface MintilConfig {
+  /** Project root directory. Defaults to `process.cwd()`. */
+  root?: string;
+  /** Port to listen on. Defaults to `process.env.PORT` or `3456`. */
+  port?: number;
+  /** Hosts allowed/supported for the frontend. Stored for reference only. */
+  hosts?: string[];
+  /**
+   * Runtime mode.
+   * - `"development"` – enables file-watching auto-reload, dev-only logs, source maps.
+   * - `"production"` – minifies CSS/JS, disables watcher.
+   * Defaults to `process.env.NODE_ENV` or `"development"`.
+   */
+  mode?: "development" | "production";
+  /** Whether to bind to all interfaces (`0.0.0.0`). Defaults to `false` (loopback only). */
+  host?: boolean;
+  /** Plugins to register. Each plugin's `setup` receives the Hono app and resolved config. */
+  plugins?: import("./plugin.ts").MintilPlugin[];
+}
+
+/** Union type of the possible runtime modes. */
+export type MintilMode = MintilConfig["mode"] & {};
+
+/**
+ * Fully resolved configuration with all defaults applied.
+ * Returned by {@link import("../core/config.ts").resolveConfig | `resolveConfig`}.
+ */
+export interface ResolvedConfig extends Required<Omit<MintilConfig, "hosts" | "plugins">> {
+  hosts: string[];
+  plugins: import("./plugin.ts").MintilPlugin[];
+}

package/src/types/index.ts

@@ -0,0 +1,4 @@
+export type { MintilConfig, ResolvedConfig, MintilMode } from "./config.ts";
+export type { PageProps, PageComponent } from "./page.ts";
+export type { ApiRequest, ApiResponse, ApiHandler, ApiMethodHandler, MintilRequest, MintilResponse } from "./api.ts";
+export type { MintilMiddleware } from "./middleware.ts";

package/src/types/middleware.ts

@@ -0,0 +1,21 @@
+import type { ApiResponse } from "./api.ts";
+
+/**
+ * A middleware function that receives an `ApiResponse` and a `next` callback.
+ *
+ * Export one as the default export of a `middleware.ts` file (at the project root,
+ * inside `api/`, or inside a sub-directory of `api/`).
+ *
+ * @example
+ * ```ts
+ * import type { MintilMiddleware } from "mintiljs";
+ *
+ * const mw: MintilMiddleware = async (c, next) => {
+ *   console.log(c.req.method, c.req.path);
+ *   await next();
+ * };
+ *
+ * export default mw;
+ * ```
+ */
+export type MintilMiddleware = (c: ApiResponse, next: () => Promise<void>) => Promise<Response | void>;

package/src/types/page.ts

@@ -0,0 +1,51 @@
+/**
+ * Props passed to every page component during SSR and client hydration.
+ * @example
+ * ```tsx
+ * export default function Home({ params, searchParams }: PageProps) {
+ *   return <div>{searchParams.get("q")}</div>;
+ * }
+ * ```
+ */
+export interface PageProps {
+  /** URL path parameters (e.g. `{ slug: "hello" }` for `blog/:slug`). */
+  params: Record<string, string>;
+  /** Parsed query-string parameters. */
+  searchParams: URLSearchParams;
+}
+
+/**
+ * A page component. Must be the default export of a file inside `pages/`.
+ * Receives {@link PageProps} (plus any extra props from `getServerSideProps`).
+ */
+export type PageComponent = (props: any) => import("react").JSX.Element;
+
+/**
+ * Context object passed to `getServerSideProps`.
+ */
+export interface ServerSidePropsContext {
+  /** URL path parameters. */
+  params: Record<string, string>;
+  /** Parsed query-string parameters. */
+  searchParams: URLSearchParams;
+  /** The original Fetch API `Request` object. */
+  req: Request;
+}
+
+/**
+ * Server-side data-fetching function.
+ *
+ * Export a function with this type from any page file. It runs on every request
+ * before the page renders. Return `{ props }` to merge additional props into the page component.
+ *
+ * @example
+ * ```ts
+ * export const getServerSideProps: GetServerSideProps = async ({ params, searchParams }) => {
+ *   const data = await db.find(params.id);
+ *   return { props: { data } };
+ * };
+ * ```
+ */
+export type GetServerSideProps = (
+  ctx: ServerSidePropsContext,
+) => Promise<{ props: Record<string, any> }>;

package/src/types/plugin.ts

@@ -0,0 +1,29 @@
+import type { Hono } from "hono";
+import type { ResolvedConfig } from "./config.ts";
+
+/**
+ * A MintilJS plugin.
+ *
+ * Register plugins via the `plugins` field in {@link import("./config.ts").MintilConfig | `MintilConfig`}.
+ *
+ * @example
+ * ```ts
+ * import type { MintilPlugin } from "mintiljs";
+ *
+ * const myPlugin: MintilPlugin = {
+ *   name: "my-plugin",
+ *   setup(app, config) {
+ *     app.get("/plugin-route", (c) => c.text("Hello from plugin!"));
+ *   },
+ * };
+ * ```
+ */
+export interface MintilPlugin {
+  /** Display name used in logs. */
+  name: string;
+  /**
+   * Called during app startup with the Hono app and resolved config.
+   * Can add routes, middleware, or modify the app.
+   */
+  setup: (app: Hono, config: ResolvedConfig) => void | Promise<void>;
+}

package/src/utils/fs.ts

@@ -0,0 +1,46 @@
+import { readdir, stat } from "node:fs/promises";
+import path from "node:path";
+
+export async function* walkFiles(dir: string): AsyncGenerator<string> {
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.name.startsWith("_")) continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      yield* walkFiles(full);
+    } else if (entry.isFile()) {
+      yield full;
+    }
+  }
+}
+
+export async function pathExists(p: string): Promise<boolean> {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function stripExt(file: string): string {
+  const ext = path.extname(file);
+  return ext ? file.slice(0, -ext.length) : file;
+}
+
+export function fileToRoutePath(filePath: string, baseDir: string): string {
+  const relative = path.relative(baseDir, filePath);
+  let noExt = stripExt(relative);
+  const parts = noExt.split(path.sep).map((part) => {
+    if (part === "(*)" || part === "*") return "*";
+    if (part.startsWith("(") && part.endsWith(")")) {
+      return part.slice(1, -1);
+    }
+    return part;
+  });
+
+  let route = "/" + parts.join("/");
+  route = route.replace(/\/index$/i, "");
+  if (!route || route === "/index") return "/";
+  return route;
+}

package/src/utils/logger.ts

@@ -0,0 +1,21 @@
+export const color = {
+  reset: "\x1b[0m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  red: "\x1b[31m",
+  cyan: "\x1b[36m",
+};
+
+export function formatDuration(ms: number): string {
+  if (ms >= 1000) {
+    return `${(ms / 1000).toFixed(2)}s`;
+  }
+  return `${ms.toFixed(0)}ms`;
+}
+
+export function statusColorFor(status: number): string {
+  if (status >= 500) return color.red;
+  if (status >= 400) return color.yellow;
+  if (status >= 300) return color.cyan;
+  return color.green;
+}

package/src/utils/network.ts

@@ -0,0 +1,14 @@
+import os from "node:os";
+
+export function getLocalIp(): string | null {
+  const interfaces = os.networkInterfaces();
+  for (const addrs of Object.values(interfaces)) {
+    if (!addrs) continue;
+    for (const addr of addrs) {
+      if (addr.family === "IPv4" && !addr.internal) {
+        return addr.address;
+      }
+    }
+  }
+  return null;
+}

package/templates/default/api/hello.ts

@@ -0,0 +1,9 @@
+import { buildGreeting } from "@app/lib/greeting";
+import type { ApiHandler } from "mintiljs";
+
+const handler: ApiHandler = (c) => {
+  const name = c.req.query("name") ?? "world";
+  return c.json({ message: buildGreeting(name) });
+};
+
+export default handler;

package/templates/default/components/card.tsx

@@ -0,0 +1,10 @@
+import React from "react";
+
+export default function Card({ title, children }: { title: string; children: React.ReactNode }) {
+  return (
+    <div className="mt-4 rounded-lg border border-gray-200 bg-white p-4 shadow-sm">
+      <h2 className="mb-2 text-lg font-semibold">{title}</h2>
+      {children}
+    </div>
+  );
+}

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

@@ -0,0 +1,26 @@
+import React from "react";
+
+export default function BaseLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="pt">
+      <head>
+        <meta charSet="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>Mintil App</title>
+        <link rel="stylesheet" href="/styles.css" />
+      </head>
+      <body className="min-h-screen bg-gray-50 text-gray-900 antialiased flex flex-col">
+        <header className="border-b border-gray-200 bg-white">
+          <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>
+          </nav>
+        </header>
+        <main className="mx-auto w-full max-w-4xl flex-1 px-4 py-10">{children}</main>
+        <footer className="border-t border-gray-200 py-6 text-center text-sm text-gray-500">
+          Built with MintilJs
+        </footer>
+      </body>
+    </html>
+  );
+}

package/templates/default/lib/greeting.ts

@@ -0,0 +1,3 @@
+export function buildGreeting(name: string) {
+  return `Hello, ${name}!`;
+}

package/templates/default/mintil.config.ts

@@ -0,0 +1,10 @@
+import type { MintilConfig } from "mintiljs";
+
+const config: MintilConfig = {
+  port: 3456,
+  hosts: ["localhost"],
+  mode: "development",
+  host: false,
+};
+
+export default config;

package/templates/default/package.json

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

package/templates/default/pages/(*).tsx

@@ -0,0 +1,11 @@
+import React from "react";
+
+export default function CatchAllPage({ params }: { params: Record<string, string> }) {
+  const path = params["*"] ?? "";
+  return (
+    <div className="text-center py-20">
+      <h1 className="text-6xl font-bold text-gray-300 mb-4">404</h1>
+      <p className="text-gray-500">No page matched <code className="rounded bg-gray-100 px-1.5 py-0.5 text-sm font-mono text-blue-700">/{path}</code>.</p>
+    </div>
+  );
+}

package/templates/default/pages/about.tsx

@@ -0,0 +1,13 @@
+import React from "react";
+
+export default function AboutPage() {
+  return (
+    <section>
+      <h1 className="mb-6 text-3xl font-bold tracking-tight">About</h1>
+      <p className="text-gray-600 leading-relaxed">
+        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>
+    </section>
+  );
+}

package/templates/default/pages/blog/(:slug).tsx

@@ -0,0 +1,12 @@
+import React from "react";
+
+export default function BlogPostPage({ params }: { params: Record<string, string> }) {
+  return (
+    <article className="prose prose-gray max-w-none">
+      <h1 className="mb-6 text-3xl font-bold capitalize tracking-tight">{params.slug}</h1>
+      <p className="text-gray-600">
+        This is a dynamic blog post page. The slug <code className="rounded bg-gray-100 px-1.5 py-0.5 text-sm font-mono text-blue-700">{params.slug}</code> was extracted from the URL.
+      </p>
+    </article>
+  );
+}

package/templates/default/pages/counter.tsx

@@ -0,0 +1,36 @@
+import React from "react";
+
+export const useClient = true;
+
+export default function CounterPage() {
+  const [count, setCount] = React.useState(0);
+  return (
+    <div className="flex flex-col items-center gap-4 py-12">
+      <h1 className="text-3xl font-bold tracking-tight">Client Counter</h1>
+      <p className="text-gray-600">This page is interactive — useState works because it is hydrated on the client.</p>
+      <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>
+      </div>
+      <button
+        onClick={() => setCount(0)}
+        className="text-sm text-gray-500 underline hover:text-gray-700"
+      >
+        reset
+      </button>
+    </div>
+  );
+}

package/templates/default/pages/index.tsx

@@ -0,0 +1,14 @@
+import React from "react";
+import Card from "@app/components/card";
+
+export default function HomePage() {
+  return (
+    <div>
+      <h1 className="mb-6 text-3xl font-bold tracking-tight">Welcome to MintilJs</h1>
+      <p className="mb-4 text-gray-600">A minimal SSR framework powered by Bun, Hono, React and Tailwind CSS.</p>
+      <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>
+  );
+}

package/templates/default/public/readme.txt

@@ -0,0 +1 @@
+This is a static asset served under /assets/readme.txt.

package/templates/default/styles.css

@@ -0,0 +1 @@
+@import "tailwindcss";

package/templates/default/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "baseUrl": ".",
+    "paths": {
+      "@app/*": ["./*"]
+    }
+  },
+  "include": ["**/*.ts", "**/*.tsx"]
+}