import { defineRoute } from "_/front/api";

export default defineRoute<
  "users/[id]/{activity}",
  [
    // validate id as number
    number,
    // activity, if given, should be one of
    TRefine<string, "posts" | "comments" | "likes">,
  ]
>(({ GET }) => [
  GET((ctx) => {
    // ctx.validated.params is typed and validated at runtime
    const { id, activity } = ctx.validated.params
  })
]);

import { defineRoute } from "_/admin/api";

type Payload = {
  email: TRefine<string, { format: "email" }>;
  password: TRefine<string, { pattern: "^(?=.*[a-zA-Z0-9])$" }>;
  name: TRefine<string, { minLength: 5; maxLength: 50 }>;
  dateOfBirth: TRefine<string, { format: "date" }>;
  agreeToTerms: boolean;
  marketingOptIn?: boolean;
}

export default defineRoute<"users">(({ POST }) => [
  POST<{
    json: Payload, 
  }>((ctx) => {
    // ctx.validated.json is typed and validated at runtime
  })
]);

import { defineRoute } from "_/admin/api";

type Page = {
  id: TRefine<string, { format: "uuid" }>;
  title: TRefine<string, { minLength: 1; maxLength: 255 }>;
  content: string;
  tags: string[];
  status: "draft" | "published" | "scheduled";
}

export default defineRoute<"pages/[id]">(({ GET }) => [
  GET<{
    response: [200, "json", Page], 
  }>(async (ctx) => {
    // response should match defined schema
  })
]);

import { use } from "_/admin/api";

export default [
  use(
    (ctx, next) => {
      // global logger
      return next();
    },
    { slot: "logger", }, 
  ),
];

import { defineRoute } from "_/front/api";

export default defineRoute<"example">(({ use, GET }) => [
  use(
    async (ctx, next) => {
      // custom logger
      return next();
    },
    { slot: "logger", }, 
  ),

  GET(async (ctx) => {
    // ...
  }),
]);

export declare module "@kosmojs/api" {
  interface UseSlots {
    logger: string; 
  }
}

import { use } from "_/front/api";

export default [
  use(async (ctx, next) => {
    // any route inside users/ folder and its subfolders
    // will wire this middleware automatically
    return next();
  })
];

🎯 What is KosmoJS? ​

KosmoJS is a meta-framework that integrates TypeScript, Vite, Koa/Hono, and your frontend framework into a clear organizational pattern. Separation of concerns isn't something you have to remember - it's built into the structure.

No proprietary abstractions. No new paradigms. Just thoughtful structure around tools you already know.

📘 Learn more

💡 Why Source Folders? ​

Applications often include multiple distinct concerns - each with different routing, auth, and config:

🔹 Public marketing site at /
🔹 Customer application at /app
🔹 Admin dashboard at /admin

Each lives in its own source folder with independent api/ and pages/ directories, sharing types and validation logic across a single project. The directory structure enforces boundaries that code review can't.

📘 Getting started · Directory-based routing

🛡️ One Source of Truth ​

KosmoJS converts your TypeScript types into runtime validators, typed fetch clients, client-side validation, and OpenAPI schemas - all from the same definitions. No duplication, no drift.

📘 Type safety · Validation · Fetch clients

⚙️ API Development ​

Build APIs inside Vite's dev server with hot-reload. Slot-based middleware gives you fine-grained control - override globals per-route or per-subtree, compose request handling precisely. What you build locally is what deploys.

📘 Dev workflow · Middleware

🚀 Production Ready ​

pnpm build produces a bundled API server, optimized frontend assets, and an optional SSR bundle. Deploy to Node.js, Deno, Bun, containers, serverless, or edge.

📘 Production build

🧠 Philosophy ​

Structure without constraints.

Opinionated about organization, unopinionated about implementation. You choose your frontend framework, state management, styling, database - everything else. The structure scales; your choices remain free.

📘 About KosmoJS · Features