Installation

Quick Start with create-kimesh

The easiest way to start a new Kimesh project is using create-kimesh:

# Interactive mode (recommended)
bun create kimesh

# With project name
bun create kimesh my-app

# Non-interactive with all options
bun create kimesh my-app --template minimal --modules tailwindcss,pinia --pm bun --install --git

Alternative package managers:

# npm
npx create-kimesh@latest

# pnpm
pnpm create kimesh

# yarn
yarn create kimesh

create-kimesh Options

Argument	Alias	Description	Default
[dir]	-	Project directory name	Prompted
--template	-t	Template to use	minimal
--modules	-m	Comma-separated modules to install	Prompted
--pm	-	Package manager (npm, yarn, pnpm, bun)	Auto-detected
--install	-i	Install dependencies after scaffolding	Prompted
--git	-g	Initialize git repository	Prompted
--force	-f	Override existing directory	false

Available Modules

When scaffolding, you can select from these modules:

Module	Description	Auto-Dependencies
tailwindcss	Utility-first CSS framework	-
shadcn	Re-usable components built with Radix Vue	tailwindcss
pinia	Intuitive store for Vue.js	-

Manual Setup

If you prefer to add Kimesh to an existing project:

1. Install Dependencies

# Using bun (recommended)
bun add kimesh

# Using pnpm
pnpm add kimesh

# Using npm
npm install kimesh

The kimesh package includes all core sub-packages:

• @kimesh/kit — Build-time engine
• @kimesh/cli — CLI commands
• @kimesh/router-runtime — Runtime router
• @kimesh/router-generator — Route code generation
• @kimesh/query — Data fetching
• @kimesh/head — Head management

2. Create kimesh.config.ts

// kimesh.config.ts
import { defineKmConfig } from 'kimesh/kit'

export default defineKmConfig({
  name: 'my-app',
  dev: {
    port: 3000,
  },
})

3. Create Routes Directory

Create src/routes/ with your route files:

src/routes/
├── __root.vue    # Root layout (wraps all routes)
├── index.vue     # Home page (/)
└── about.vue     # About page (/about)

4. Root Layout

src/routes/__root.vue — The root layout wraps all routes:

<template>
  <div id="app">
    <nav>
      <!-- KmLink is auto-imported -->
      <KmLink to="/">Home</KmLink>
      <KmLink to="/about">About</KmLink>
    </nav>
    <main>
      <RouterView />
    </main>
  </div>
</template>

Note: KmLink and RouterView are auto-imported — no explicit import statement needed.

5. Page Components

src/routes/index.vue — Home page:

<template>
  <h1>Welcome to Kimesh</h1>
  <p>Type-safe file-based routing for Vue.</p>
</template>

src/routes/about.vue — About page:

<template>
  <h1>About</h1>
  <p>Learn more about our application.</p>
</template>

6. Configure package.json

{
  "scripts": {
    "prepare": "km prepare",
    "postinstall": "km prepare",
    "dev": "km dev",
    "build": "km build"
  }
}

7. Configure TypeScript

{
  "extends": "./.kimesh/tsconfig.json",
  "compilerOptions": {
    "strict": true
  }
}

8. Run Development Server

bun dev

Kimesh will automatically:

• Scan your src/routes directory
• Generate routes in .kimesh/routes.gen.ts
• Generate types in .kimesh/typed-routes.d.ts
• Auto-import Vue, Vue Router, and Kimesh APIs
• Hot-reload when files change

Auto-Imports

Kimesh auto-imports commonly used APIs so you don't need explicit import statements:

Vue APIs — ref, reactive, computed, watch, onMounted, etc.

Vue Router — useRoute, useRouter, onBeforeRouteLeave, etc.

Kimesh APIs — createFileRoute, defineRoute, useNavigate, useSearch, useParams, KmOutlet, KmLink, KmDeferred, defineKimeshMiddleware, navigateTo, abortNavigation, etc.

Your own composables from composables/ and utilities from utils/ directories are also auto-imported.

Project Structure

A typical Kimesh project:

my-app/
├── src/
│   ├── routes/
│   │   ├── __root.vue        # Root layout
│   │   ├── index.vue         # /
│   │   ├── about.vue         # /about
│   │   ├── posts.vue         # Layout for /posts/*
│   │   └── posts/
│   │       ├── index.vue     # /posts
│   │       ├── $postId.vue   # /posts/:postId
│   │       └── -posts.data.ts # Query definitions (excluded from routing)
│   ├── components/           # Auto-imported components
│   ├── composables/          # Auto-imported composables
│   └── middleware/            # Route middleware
├── .kimesh/                   # Generated files (gitignored)
│   ├── routes.gen.ts
│   ├── tsconfig.json
│   └── auto-imports.d.ts
├── kimesh.config.ts
├── tsconfig.json
└── package.json

Next Steps

• Configuration — Configure your Kimesh project
• Routing — Learn routing fundamentals
• Data Fetching — Load data before routes render
• Layers — Build modular applications