---
url: /start.md
description: Get a KosmoJS project running in under five minutes.
---

Zero to a working route in under five minutes.

## Create a Project

### Quick Start | Create a Project | npm

```sh
npm create kosmo
```

### Quick Start | Create a Project | pnpm

```sh
pnpm create kosmo
```

### Quick Start | Create a Project | yarn

```sh
yarn create kosmo
```

A short interactive setup walks you through the choices that matter:
the name, the frontend and the backend you want to build with.
Everything else starts with sensible defaults.

Pick whatever feels familiar - nothing here is set in stone,
and any folder you add later can make entirely different choices.

Use `.` to bootstrap in the current directory:

```sh
npm create kosmo .
```

***

After bootstrap, `cd` into freshly created project (unless bootstrapped in the current folder):

```sh
cd ./demo
```

#### Install Dependencies

##### Quick Start | Install Dependencies | npm

```sh
npm install
```

##### Quick Start | Install Dependencies | pnpm

```sh
pnpm install
```

##### Quick Start | Install Dependencies | yarn

```sh
yarn install
```

The scaffold is complete, everything comes filled in,
including a default index page and, with a backend, a default index route.
The routes you add next sit alongside them.

## Start the dev server

The dev server watches your routes and recomputes as you work -
and seeds starter code into any route or page file you create empty:

### Quick Start | Start the dev server | npm

```sh
npm run dev
```

### Quick Start | Start the dev server | pnpm

```sh
pnpm dev
```

### Quick Start | Start the dev server | yarn

```sh
yarn dev
```

Your app is now running at `http://localhost:4556`, serving the default index page.

## Create a route

Create the file `api/users/[id]/index.ts` - KosmoJS detects it
and seeds starter code automatically.

Replace the seeded content with something real:

### Quick Start | Create a route | Hono

```ts
// Hono: api/users/[id]/index.ts
import { defineRoute } from "_/api";

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

### Quick Start | Create a route | H3

```ts
// H3: api/users/[id]/index.ts
import { defineRoute } from "_/api";

export default defineRoute<"users/[id]">(({ GET }) => [
  GET(async (event) => {
    const { id } = event.context.params;
    return { id, name: "Jane Smith", email: "jane@example.com" };
  }),
]);
```

### Quick Start | Create a route | Koa

```ts
// Koa: api/users/[id]/index.ts
import { defineRoute } from "_/api";

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

Visit `http://localhost:4556/api/users/123`. You should see JSON.

## Create a page

With the dev server still running, create `pages/users/[id]/index.tsx`
(or `.vue` / `.svelte` / `.mdx`).
KosmoJS seeds a placeholder component - replace it with a page that fetches from your API route.
React and SolidJS fetch in the component here;
Vue, Svelte and MDX read through a `loader` export instead (resolved before render),
so they need no loading state:

### Quick Start | Create a page | React

```tsx
// React: pages/users/[id]/index.tsx
import { useState, useEffect } from "react";
import { useParams } from "react-router";
import fetchClients from "_/fetch";

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

export default function UserPage() {
  const { id } = useParams();
  const [user, setUser] = useState(null);

  useEffect(() => { GET([id]).then(setUser); }, [id]);

  return user
    ? <div><h1>{user.name}</h1><p>{user.email}</p></div>
    : <div>Loading...</div>;
}
```

### Quick Start | Create a page | Solid

```tsx
// Solid: pages/users/[id]/index.tsx
import { useParams } from "@solidjs/router";
import { 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]));

  return user()
    ? <div><h1>{user().name}</h1><p>{user().email}</p></div>
    : <div>Loading...</div>;
}
```

### Quick Start | Create a page | Vue

```vue
<!-- Vue: pages/users/[id]/index.vue -->
<script lang="ts">
import fetchClients from "_/fetch";

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

// a plain <script> block, since <script setup> cannot hold ES exports
export const loader = ({ params }) => GET([params.id]);
</script>

<script setup lang="ts">
import { useLoaderData } from "_/use";

const user = useLoaderData();
</script>

<template>
  <div><h1>{{ user.name }}</h1><p>{{ user.email }}</p></div>
</template>
```

### Quick Start | Create a page | Svelte

```svelte
<!-- Svelte: pages/users/[id]/index.svelte -->
<script module lang="ts">
import fetchClients from "_/fetch";

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

export const loader = ({ params }) => GET([params.id]);
</script>

<script lang="ts">
import { useLoaderData } from "_/use";

const user = useLoaderData();
</script>

<div><h1>{user.name}</h1><p>{user.email}</p></div>
```

### Quick Start | Create a page | MDX

```mdx
{/* MDX: pages/users/[id]/index.mdx */}
import fetchClients from "_/fetch";
import { useLoaderData } from "_/use";

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

export const loader = ({ params }) => GET([params.id]);

export const UserPage = () => {
  const user = useLoaderData();
  return <div><h1>{user.name}</h1><p>{user.email}</p></div>;
};

<UserPage />
```

Visit `http://localhost:4556/users/123`. Your page renders with data from the API.

The fetch client is fully typed - `user.name` and `user.email` autocomplete in your editor,
and invalid parameters are caught before the request leaves the browser.

## What just happened

Your folder structure became your routes:

```
api/users/[id]/index.ts     ->  /api/users/:id
pages/users/[id]/index.tsx  ->  /users/:id
```

`[id]` is a required parameter. `{id}` makes it optional. `{...path}` matches any depth.
The parallel structure between `api/` and `pages/` is intentional -
API endpoints and their corresponding pages are always easy to find.

The fetch client is derived automatically from your API route definition.
Change the API types, and the client updates with them - no manual sync.

***

That's the foundation. From here:

* [Tutorial](/tutorial.md) - validation, middleware, fetch clients, pages, SSR
* [Project Structure](/essentials/project-structure.md) - what lives where, and what `@/` `~/` `_/` mean
* [Configuration](/essentials/config.md) - every `kosmo.config.ts` option
* [CLI](/cli/intro.md) - every command and flag, interactive and non-interactive
* [Routing](/routing/intro.md) - parameters, mixed segments, power syntax
* [Framework Support](/essentials/frameworks.md) - what each framework does and doesn't support
* [Features](/features.md) - everything KosmoJS provides, at a glance
