import { defineRoute } from "_/admin/api/users/[id]";

export default defineRoute<[
  number // validate id as number
]>(({ GET }) => [
  GET((ctx) => {
    // ctx.typedParams.id is typed and validated at runtime
    const { id } = ctx.typedParams
  })
]);

import { defineRoute } from "_/admin/api/users/[id]";

export default defineRoute<[
  // validate id as positive integer
  TRefine<number, { minimum: 1, multipleOf: 1 }>
]>(({ GET }) => [
  GET((ctx) => {
    // ctx.typedParams.id is typed and validated at runtime
    const { id } = ctx.typedParams
  })
]);

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

export default defineRoute(({ POST }) => [
  POST<{
    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;
  }>((ctx) => {
    // ctx.payload is typed and validated at runtime
  })
]);

import { defineRoute } from "_/front/api/blog/[...page]";

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(({ GET }) => [
  GET<
    never, // no payload validation
    Page  // validate response to be a valid Page
  >(async (ctx) => {
    // ctx.body should match the schema defined above,
    // otherwise validation fails and an error response is returned
  })
]);

import { use } from "@kosmojs/api";
import bodyparser from "@kosmojs/api/bodyparser";

export default [
  use(
    bodyparser.json(), 
    {
      slot: "bodyparser", 
      on: ["POST", "PUT", "PATCH"],
    },
  ),
];

import bodyparser from "@kosmojs/api/bodyparser";
import { defineRoute } from "_/admin/api/files/upload";

export default defineRoute(({ use, POST }) => [
  use(
    bodyparser.form(), // use form bodyparser
    {
      slot: "bodyparser", 
      on: ["POST"],
    },
  ),

  POST((ctx) => {
    // ctx.payload now contains parsed form data
  })
]);

🎯 The What ​

KosmoJS is a structured Vite template that keeps your full-stack concerns aligned.

Rather than inventing yet another framework, KosmoJS integrates proven tools - TypeScript, Vite, Koa, 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 to learn. Just thoughtful structure around tools you already know.

📘 Learn more

💡 The Why ​

Multiple source folders for distinct concerns - each with its own API and pages directories, eg.:

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

All in one monorepo-like project, each with independent routing and configuration, yet sharing types and validation logic.
API / Pages separation keeps server and client code from mixing. Your directory structure enforces boundaries that code review can't.

📘 Getting started · Directory-based routing

📦 The How ​

At its core, KosmoJS structures full-stack Vite development around a Koa application.

🔹 Vite handles your frontend builds and organizational structure.
🔹 Koa powers your API runtime with runtype validation and middleware composition.
🔹 KosmoJS is the structured template that brings them together.

🛡️ Type Safety & Validation ​

KosmoJS converts your types into runtime validation routines, ensuring type safety beyond compile time - no duplication, no drift.

Define parameter types, payload structures, and response shapes once. KosmoJS generates:

• Runtime validators for your API
• Typed fetch clients for your frontend
• Client-side validation that catches errors before requests
• As well as OpenAPI schema for your entire API

Everything stays aligned because everything derives from the same source of truth.

📘 Type safety overview · Validation · Payload validation

⚡ Generated Fetch Clients ​

Every API route gets a fully-typed fetch client with built-in validation. Your frontend knows exactly what parameters each endpoint expects, what payload structure it accepts, and what response shape it returns.

Invalid data is caught client-side, before network requests. Your API never processes malformed requests.

📘 Fetch clients intro · Getting started · Client-side validation

⚙️ API Development ​

Build APIs directly inside Vite's dev server with hot-reload support.

Slot-based middleware gives you fine-grained control - override global middleware per endpoint, compose request handling precisely, maintain consistent patterns across routes.

Development and production use the same structure - what you build locally is what deploys.

📘 Dev workflow · Middleware patterns

🚀 Production Ready ​

pnpm build produces deployment-ready output:

• a bundled API server
• optimized frontend assets
• an SSR bundle enabling smooth server-side rendering

Deploy to any Node.js environment: traditional servers, containers, serverless platforms, or edge runtimes.

📘 Production build guide

🧠 Philosophy ​

Structure without constraints.

KosmoJS is opinionated about organization but unopinionated about implementation. Clear boundaries between API and pages. Obvious locations for shared types and utilities. Separation of concerns built into the filesystem.

You choose your frontend framework, state management, styling approach, database, and everything else.
The structure scales; your choices remain free.

📘 About KosmoJS · Features