Directory Structure

A Kimesh project follows a convention-based directory structure. All conventions can be customized via kimesh.config.ts.

Overview

my-app/
├── src/                        # Source directory (configurable via srcDir)
│   ├── routes/                 # File-based routes
│   │   ├── __root.vue          # Root layout
│   │   ├── index.vue           # / (home)
│   │   └── about.vue           # /about
│   ├── components/             # Auto-imported components
│   ├── composables/            # Auto-imported composables
│   ├── utils/                  # Auto-imported utilities
│   ├── middleware/              # Route middleware definitions
│   ├── plugins/                # Runtime plugins
│   ├── assets/                 # Static assets (processed by Vite)
│   └── app.vue                 # App entry (optional)
├── public/                     # Static files (served as-is)
├── layers/                     # Local layers
├── .kimesh/                    # Generated files (gitignored)
│   ├── tsconfig.json           # Path aliases & TypeScript config
│   ├── routes.gen.ts           # Generated route definitions
│   ├── auto-imports.d.ts       # Auto-import type declarations
│   ├── components.d.ts         # Component type declarations
│   ├── context.d.ts            # Kimesh context types
│   ├── modules.ts              # Module metadata
│   └── plugins.mjs             # Runtime plugin config
├── kimesh.config.ts            # Kimesh configuration
├── tsconfig.json               # Extends .kimesh/tsconfig.json
└── package.json

src/routes/

File-based routes. Every .vue file becomes a route automatically.

File Pattern	Purpose
index.vue	Index route for the directory path
about.vue	Static route /about
$id.vue	Dynamic route segment /:id
$.vue	Catch-all route
__root.vue	Root layout (wraps all routes)
_name.vue	Pathless layout (wraps children, no URL segment)
(group)/	Group folder (organization only, no URL segment)
-utils.ts	Ignored file (excluded from routing)

::callout{type="info"} Configured via router.routesDir (default: "routes") ::

src/components/

Vue components placed here are auto-imported globally. No import statements needed.

components/
├── AppButton.vue        # <AppButton>
├── AppCard.vue          # <AppCard>
└── layout/
    ├── Header.vue       # <LayoutHeader>
    └── Footer.vue       # <LayoutFooter>

Nested directories add a prefix: layout/Header.vue → <LayoutHeader>.

::callout{type="info"} Configured via components.dirs and components.prefix ::

src/composables/

Composables placed here are auto-imported. Export them as named exports or default exports.

composables/
├── useAuth.ts           # useAuth()
├── useCounter.ts        # useCounter()
└── useTheme.ts          # useTheme()

::callout{type="info"} Configured via autoImport.dirs (default: ["composables", "utils"]) ::

src/utils/

Utility functions placed here are auto-imported, same as composables.

utils/
├── formatDate.ts        # formatDate()
└── validators.ts        # Named exports auto-imported

src/middleware/

Global and named middleware for route navigation guards.

middleware/
├── 00.auth.global.ts     # Global middleware (runs on every navigation)
├── 01.analytics.global.ts
└── admin.ts              # Named middleware (opt-in per route)

• Files ending in .global.ts run on every navigation
• Numeric prefixes control execution order
• Named middleware is referenced in createFileRoute options

src/plugins/

Runtime plugins that run when the app initializes.

plugins/
├── 01.analytics.ts      # Runs on app init
└── 02.error-handler.ts

// plugins/01.analytics.ts
export default defineKimeshRuntimePlugin({
  name: 'analytics',
  setup({ app, router }) {
    router.afterEach((to) => {
      trackPageView(to.fullPath)
    })
  },
})

::callout{type="info"} Configured via dir.plugins (default: "plugins") ::

src/assets/

Static assets processed by Vite (images, fonts, CSS, etc.):

assets/
├── css/
│   └── main.css
├── images/
│   └── logo.svg
└── fonts/
    └── Inter.woff2

Import in components: import logo from '~/assets/images/logo.svg'

public/

Files served as-is at the root URL. Not processed by Vite.

public/
├── favicon.ico          # /favicon.ico
├── robots.txt           # /robots.txt
└── images/
    └── og-image.png     # /images/og-image.png

.kimesh/

Auto-generated directory. Do not edit manually. Add to .gitignore.

Generated by km prepare and updated automatically during km dev.

File	Purpose
tsconfig.json	Path aliases for TypeScript
routes.gen.ts	Generated route definitions
auto-imports.d.ts	Auto-import type stubs
components.d.ts	Component type stubs
context.d.ts	Kimesh context types
modules.ts	Module metadata
plugins.mjs	Runtime plugin registration

layers/

Local layers directory. Each subdirectory is a self-contained layer.

layers/
├── ui-layer/
│   ├── src/
│   │   ├── routes/
│   │   ├── components/
│   │   └── composables/
│   └── kimesh.config.ts
└── auth-layer/
    ├── src/
    │   └── routes/
    └── kimesh.config.ts

::callout{type="info"} Configured via layers.dirs (default: ["layers"]) ::

kimesh.config.ts

The main configuration file. See Configuration Reference.

tsconfig.json

Your project's TypeScript configuration. Should extend the generated config:

{
  "extends": "./.kimesh/tsconfig.json"
}