A step-by-step walkthrough covering everything KosmoJS provides.

🚀 Create Your Project

npm

npm create kosmo
# non-interactive: npm create kosmo --name my-app

pnpm

pnpm create kosmo
# non-interactive: pnpm create kosmo --name my-app

yarn

yarn create kosmo
# non-interactive: yarn create kosmo --name my-app

cd ./my-app

📦 Install Dependencies

npm

npm install

pnpm

pnpm install

yarn

yarn install

📁 Create a Source Folder

KosmoJS doesn't create a source folder automatically - you add them as needed, one per distinct concern (main app, admin panel, marketing site, etc.). Each is independent with its own set of frameworks, config, base URL, etc.

npm

npm run +folder

pnpm

pnpm +folder

yarn

yarn +folder

You'll be prompted for folder name, base URL, framework, backend, and SSR/SSG.

Non-interactive mode is also supported:

• --name
• --base
• --framework solid|react|vue|mdx
• --backend koa|hono
• --ssr
• --ssg

npm

npm run +folder -- --name front --base / --framework solid --backend koa

pnpm

pnpm +folder --name front --base / --framework solid --backend koa

yarn

yarn +folder --name front --base / --framework solid --backend koa

Creating a source folder adds framework-specific dependencies to package.json. Install them:

npm

npm install

pnpm

pnpm install

yarn

yarn install

🛣️ Directory-Based Routing

Folder names become URL segments. Each route requires an index file:

api/
  users/
    index.ts          ➜ /api/users
    [id]/
      index.ts        ➜ /api/users/:id

pages/
  users/
    index.tsx         ➜ /users
    [id]/
      index.tsx       ➜ /users/:id

Parameters: [id] required · {id} optional · {...path} splat. Same pattern for API and pages - learn once, use everywhere.

Read more ➜

💡 Path Mappings

Your project starts with a minimal tsconfig.json:

tsconfig.json

{ "extends": "./lib/tsconfig.base.json" }

The extended config provides path mappings used throughout the framework. You can add your own paths, but these prefixes are reserved:

• @/* - Root-level imports
• ~/* - Source folder imports
• _/* - Generated code imports

✅ Create Your First API Route

Create api/users/[id]/index.ts - KosmoJS detects the file and generates boilerplate:

Koa

import { defineRoute } from "_/api";

export default defineRoute<"users/[id]">(({ GET }) => [
  GET(async (ctx) => {
    ctx.body = "Automatically generated route: [ users/[id] ]"
  }),
]);

Hono

import { defineRoute } from "_/api";

export default defineRoute<"users/[id]">(({ GET }) => [
  GET(async (ctx) => {
    ctx.text("Automatically generated route: [ users/[id] ]");
  }),
]);

Some editors show generated content immediately; others need a brief unfocus/refocus.

Replace with real logic:

Koa

import { defineRoute } from "_/api";

type User = { id: number; name: string; email: string }

export default defineRoute<"users/[id]">(({ GET }) => [
  GET(async (ctx) => {
    const { id } = ctx.params;
    const user: User = { id: Number(id), name: "Jane Smith", email: "jane@example.com" };
    ctx.body = user;
  }),
]);

Hono

import { defineRoute } from "_/api";

type User = { id: number; name: string; email: string }

export default defineRoute<"users/[id]">(({ GET }) => [
  GET(async (ctx) => {
    const { id } = ctx.req.param();
    const user: User = { id: Number(id), name: "Jane Smith", email: "jane@example.com" };
    ctx.json(user);
  }),
]);

Start the dev server and visit http://localhost:4556/api/users/123:

npm

npm run dev

pnpm

pnpm dev

yarn

yarn dev

Read more ➜

🛡️ Add Validation

Parameter Validation

Pass a tuple as the second type argument to refine params. Each position maps to a route parameter in order:

Koa

export default defineRoute<"users/[id]", [
  number 
]>(({ GET }) => [
  GET(async (ctx) => {
    const { id } = ctx.validated.params; // number, not string
    const user: User = { id, name: "Jane Smith", email: "jane@example.com" };
    ctx.body = user;
  }),
]);

Hono

export default defineRoute<"users/[id]", [
  number 
]>(({ GET }) => [
  GET(async (ctx) => {
    const { id } = ctx.validated.params; // number, not string
    const user: User = { id, name: "Jane Smith", email: "jane@example.com" };
    ctx.json(user);
  }),
]);

Use VRefine for additional constraints (no import needed):

defineRoute<"users/[id]", [
  VRefine<number, { minimum: 1, multipleOf: 1 }> // positive integer
]>

ctx.params/ctx.req.param() still exist but return untyped strings - prefer ctx.validated.params.

Payload/Response Validation

The first type argument to each method handler defines validation targets.

Metadata targets (any method): query · headers · cookies

Body targets (mutually exclusive, POST/PUT/PATCH/DELETE only): json · form · raw

Koa

type CreateUserPayload = {
  name: string;
  email: VRefine<string, { format: "email" }>;
  age?: number;
}

export default defineRoute<"users">(({ POST }) => [
  POST<{
    json: CreateUserPayload,
    response: [200, "json", User] 
  }>(async (ctx) => {
    const { name, email, age } = ctx.validated.json;
    ctx.body = { id: 1, name, email, age };
  }),
]);

Hono

type CreateUserPayload = {
  name: string;
  email: VRefine<string, { format: "email" }>;
  age?: number;
}

export default defineRoute<"users">(({ POST }) => [
  POST<{
    json: CreateUserPayload,
    response: [200, "json", User] 
  }>(async (ctx) => {
    const { name, email, age } = ctx.validated.json;
    ctx.json({ id: 1, name, email, age });
  }),
]);

Payload is validated before your handler runs. Response is validated before it's sent.

Read more ➜

▶️ Add Middleware

For simple cases, wire middleware inline with use:

import { logRequest } from "~/middleware/logging";

export default defineRoute<"users/[id]">(({ use, GET }) => [
  use(logRequest),
  GET(async (ctx) => { /* ... */ }),
]);

For anything shared across routes, use cascading middleware instead. Create api/users/use.ts - it wraps every route under /api/users automatically:

api/users/use.ts

import { use } from "_/api";

export default [
  use(async (ctx, next) => {
    // runs for every route under /api/users
    return next();
  })
];

No imports in route files, no repetition. Parent use.ts files wrap child routes automatically.

Read more ➜

📥 Fetch Clients

Fetch clients are fully typed and validated client-side using the same high-performance TypeBox validators as the server - identical results, no duplication, no drift.

Invalid requests are caught before they leave the browser:

SolidJS

import { useParams, createAsync } from "@solidjs/router";
import fetchClients from "_/fetch";

const { GET } = fetchClients["users/[id]"];

export default function UserPage() {
  const params = useParams();
  const user = createAsync(() => GET([params.id]));
  // ...
}

React

import { useState, useEffect } from "react";
import { useParams } from "react-router";
import fetchClients from "_/fetch";

const { GET } = fetchClients["users/[id]"];

export default function UserPage() {
  const params = useParams();
  const [user, setUser] = useState(null);
  useEffect(() => { GET([params.id]).then(setUser); }, [params.id]);
  // ...
}

Vue

<script setup lang="ts">
import { ref, onMounted } from "vue";
import { useRoute } from "vue-router";
import fetchClients from "_/fetch";

const { GET } = fetchClients["users/[id]"];
const route = useRoute();
const user = ref(null);
onMounted(async () => { user.value = await GET([route.params.id]); });
</script>

Server-side validation still runs even when endpoints are called directly - client validation is additive, not a substitute.

Read more ➜

🎨 Create Client Pages

Pages live in pages/ and follow the same directory-based routing as API routes. Create pages/users/index.tsx - KosmoJS generates framework-specific boilerplate.

Add a layout for shared UI across route groups - create pages/users/layout.tsx:

pages/
└── users/
    ├── layout.tsx    ← wraps all pages under /users
    └── index.tsx

Layouts can be nested - deeper layouts wrap inner layouts, matching your route hierarchy.

Read more ➜

⚡ Server-Side Rendering

Enable when creating a source folder (--ssr), or add it later in kosmo.config.ts:

kosmo.config.ts

import { defineConfig, ssrGenerator } from "@kosmojs/dev";

export default defineConfig({
  generators: [
    // ...
    ssrGenerator(),
  ]
});

Restart dev server after adding new generators.

KosmoJS generates entry/server.ts - your SSR orchestration file. Critical CSS is extracted and inlined automatically; remaining styles load asynchronously.

Build and run:

pnpm build
node dist/front/ssr/server.js -p 4556

The API server and SSR server are bundled separately - deploy, scale, and run them independently.

Read more ➜

🗂️ Multiple Source Folders

Add more source folders as your project grows - each with its own framework stack, base URL, and build output. They develop and deploy independently but share types, validation logic, and infrastructure.

pnpm +folder          # add a new source folder
pnpm dev              # runs all source folders in parallel
pnpm build admin      # build a specific folder

---

Next Steps

Core patterns: Routing · Validation · Middleware · Layouts · Fetch Clients

Advanced: VRefine · OpenAPI · Production Builds