Kimesh

Appearance

Kimesh Codebase Summary ​

Version: 0.2.23 Generated: January 28, 2026 Total Files: 418 | Total Tokens: 372,030 | Monorepo Size: 1.5MB code

Repository Structure ​

kimesh/
├── packages/          # Core framework packages (11 packages)
├── modules/           # Official extension modules (3 modules)
├── playground/        # Example applications
├── tooling/           # Build and development tools
├── docs/              # VitePress documentation
└── scripts/           # Release and maintenance scripts

Packages Overview ​

Core Packages ​

1. kimesh (Root Package) ​

Path: packages/kimesh/Purpose: Main entry point and export aggregator Key Exports:

  • . - Main entry
  • ./kit - Build-time plugin engine
  • ./config - Configuration utilities
  • ./head - Head/meta management
  • ./query - Data fetching layer
  • ./router-runtime - Runtime router integration
  • ./router-runtime/default-app - Default app factory

Files: 9 files, ~200 lines

  • src/index.ts - Exports aggregation
  • src/kit.ts - Kit export
  • src/config.ts - Config utilities
  • src/head.ts - Head components and composables
  • src/head-plugin.ts - Head plugin factory
  • src/query.ts - Query integration
  • src/router-runtime.ts - Router runtime exports
  • bin/kimesh.mjs - CLI entry point

Dependencies: @kimesh/cli, @kimesh/head, @kimesh/kit, @kimesh/query, @kimesh/router-runtime

2. @kimesh/kit (Build Engine) ​

Path: packages/kit/Purpose: Vite plugin and build-time code generation Largest Package: 37 source files, ~12,000 tokens (largest single file: plugin.ts)

Key Modules:

  • core/kimesh.ts - Core framework logic
  • core/plugin.ts - Vite plugin factory
  • kit/ - Kit utilities (10+ files)
    • alias.ts - Path alias resolution
    • components.ts - Component discovery
    • imports.ts - Auto-import system
    • route-rules.ts - Route configuration
    • tsconfig-generator.ts - Type generation
    • vite.ts - Vite integration
    • templates.ts - Code generation templates
  • vite/plugin.ts - Main Vite plugin (3.2% of codebase)
  • vite/layer-alias-plugin.ts - Layer alias resolution
  • hmr/watcher.ts - Hot module reloading
  • types/ - Type definitions (6 files)
  • errors/ - Error handling (2 files)

Build Process:

  1. Phase 1: Configuration loading, route discovery, layer resolution
  2. Phase 2: Type generation, component scanning, auto-import registry

3. @kimesh/router-generator (Route Generation) ​

Path: packages/router-generator/Purpose: File-based route scanning and generation

Key Features:

  • File pattern matching for route definitions
  • Nested route/layout support
  • Route merging for complex hierarchies
  • OXC parser integration
  • Type-safe route configuration

Files:

  • src/route-merger.ts - Route merging logic
  • src/route-merger.test.ts - Comprehensive test suite (7,000+ tokens)
  • src/scanner.ts - File scanning
  • src/types.ts - Type definitions

4. @kimesh/router-runtime (Runtime Router) ​

Path: packages/router-runtime/Purpose: Vue Router integration and runtime features

Key Exports:

  • Router composition API
  • Route definition helpers
  • Middleware pipeline
  • Type-safe route utilities
  • Navigation composables

Files:

  • src/router.ts - Router creation
  • src/middleware.ts - Middleware pipeline
  • src/composables/ - Vue composables (5+ files)
  • src/types/ - Runtime types

5. @kimesh/auto-import (Code Generation) ​

Path: packages/auto-import/Purpose: OXC-powered auto-import system with layer support

Architecture:

  • scanner/ - File scanning (2 files)
    • oxc-scanner.ts - OXC AST parsing
    • reference-detector.ts - Reference detection
  • registry/ - Import registry (3 files)
    • builder.ts - Registry building
    • conflict-resolver.ts - Name conflict resolution
    • utils.ts - Registry utilities
  • script/ - Script transformation (4 files)
    • injector.ts - Import injection
    • detector.ts - Import detection
    • plugin.ts - Plugin integration
  • template/ - Template rendering (3 files)
    • resolver.ts - Template variable resolution
    • plugin.ts - Template plugin
  • vite/ - Vite integration (2 files)
    • plugin.ts - Main Vite plugin
    • components.ts - Component registration

6. @kimesh/cli (Command Line Interface) ​

Path: packages/cli/Purpose: CLI commands and project management

Commands:

  • init - New project scaffolding
  • dev - Development server
  • build - Production build
  • generate - Explicit code generation
  • prepare - Pre-build tasks
  • layer - Layer management

Files:

  • src/commands/ - Command implementations (7 files)
  • src/utils/ - CLI utilities
  • bin/km.mjs - CLI entry point

7. @kimesh/head (SEO & Meta) ​

Path: packages/head/Purpose: Head/meta management (@unhead/vue integration)

Components:

  • KmHead - Head container
  • KmHtml - HTML attributes
  • KmBody - Body attributes
  • KmTitle - Page title
  • KmMeta - Meta tags
  • KmLink - Link tags
  • KmScript - Script tags
  • KmStyle - Style tags

Composables:

  • useHead() - Head management
  • useHeadSafe() - Safe head updates
  • useRouteHead() - Route-specific head
  • useSEOMeta() - SEO utilities

8. @kimesh/query (Data Fetching) ​

Path: packages/query/Purpose: TanStack Query integration and utilities

Exports:

  • useQuery() - Query composable
  • useMutation() - Mutation composable
  • queryClient - Shared client
  • defineQueryOptions() - Type-safe option definition

9. @kimesh/layers (Configuration) ​

Path: packages/layers/Purpose: Layer system for monorepo configuration inheritance

Features:

  • Layer discovery from directories
  • Configuration merging (c12, defu)
  • Environment-specific configs
  • Type generation for layer configs

Files:

  • src/layer.ts - Layer logic
  • src/resolver.ts - Layer resolution
  • src/scanner.ts - Layer scanning

10. @kimesh/create-kimesh (Scaffolder) ​

Path: packages/create-kimesh/Purpose: Project initialization and scaffolding

Features:

  • Interactive prompts for project setup
  • Module selection and installation
  • Layer configuration
  • Template selection
  • Host/monorepo detection

Modules:

  • src/prompts/ - CLI prompts (7 files)
  • src/utils/ - Utility functions
  • src/modules/ - Module registry

11. tooling (Build System) ​

Path: tooling/Purpose: Shared development and build configuration

Modules Overview ​

Official Extension Modules ​

1. @kimesh/pinia (State Management) ​

Path: modules/pinia/Purpose: Pinia store auto-registration and DevTools integration

Files:

  • src/module.ts - Module definition
  • src/plugin.ts - Plugin factory
  • src/composables/use-pinia.ts - Store composable
  • src/types.ts - Type definitions

Features:

  • Auto-discovery of stores
  • DevTools integration
  • Type-safe store access
  • Hot module reload support

2. @kimesh/shadcn (Component Library) ​

Path: modules/shadcn/Purpose: Shadcn component auto-registration with OXC parsing

Files:

  • src/module.ts - Module definition
  • src/scanner.ts - Component scanning
  • src/types.ts - Type definitions

Features:

  • Component auto-discovery
  • OXC-powered parsing
  • Registry building
  • Type generation

3. @kimesh/tailwindcss (CSS Framework) ​

Path: modules/tailwindcss/Purpose: Tailwind CSS integration with @source directives

Files:

  • src/module.ts - Module definition
  • src/transform.ts - Config transformation
  • src/types.ts - Type definitions

Features:

  • Automatic content discovery
  • @source directive support
  • Layer-aware configuration
  • CSS optimization

File Organization Patterns ​

Package Structure ​

Each package follows a standard structure:

packages/package-name/
├── src/
│   ├── index.ts              # Main export
│   ├── types.ts              # Type definitions
│   ├── [feature]/
│   │   ├── index.ts          # Feature export
│   │   └── [submodule].ts    # Implementation
│   └── [feature].test.ts      # Tests
├── package.json
├── tsconfig.json
├── tsdown.config.ts
├── README.md
└── augment.d.ts              # Vue augmentation (if needed)

Naming Conventions ​

  • Directories: kebab-case (src/route-generator/)
  • Files: kebab-case (route-merger.ts)
  • Functions: camelCase (generateRoutes())
  • Classes: PascalCase (RouteGenerator)
  • Interfaces: PascalCase with I prefix optional (KimeshConfig, RouteDefinition)
  • Tests: Same name with .test.ts suffix (route-merger.test.ts)
  • Privates: Leading underscore (_internal.ts)

File Size Guidelines ​

  • Standard file limit: 200 lines maximum
  • Larger features split across multiple files
  • Examples:
    • kit/plugin.ts: 3.2% of total (exceeds limit for critical code)
    • router-generator/route-merger.test.ts: Comprehensive tests
    • Most implementation files: 50-150 lines

Module Definition Pattern ​

Each package exports:

typescript
// Index file structure
export * from './types'
export * from './feature1'
export * from './feature2'

Test files colocated with implementation:

feature.ts
feature.test.ts

Build Configuration ​

Turborepo Setup ​

File: turbo.json

  • Task orchestration: build, dev, typecheck, test, clean
  • Filter excludes: playground, docs
  • Caching configuration

TypeScript Configuration ​

File: tsconfig.json

  • Strict mode enabled
  • Module: ES2020
  • Target: ES2020
  • Path aliases for all packages

Vite Configuration ​

File: vitest.config.ts

  • Test framework: Vitest 4.0.17
  • Coverage: v8 provider
  • Watch mode: enabled

Code Quality Tools ​

  • Linting: oxlint (Rust-based, ~1.42.0)
  • Formatting: oxfmt (Rust-based, ~0.27.0)
  • Coverage: Vitest v8
  • Bundling: tsdown 0.20.0-beta.3

Key Directories ​

src/ (Source Code) ​

  • Framework implementation
  • Type definitions
  • Plugin logic
  • Component templates

.kimesh/ (Generated) ​

  • routes.gen.ts - Generated route configuration
  • typed-routes.d.ts - Type definitions for routes
  • imports.gen.ts - Auto-import registry
  • components.gen.ts - Component registry

playground/ (Examples) ​

  • apps/host/ - Main host application
  • apps/todo/ - Todo app example
  • Real-world usage examples

scripts/ (Maintenance) ​

  • release.ts - Release automation
  • bump.ts - Version bumping
  • bump-nightly.ts - Nightly builds

.github/workflows/ (CI/CD) ​

  • ci.yml - Continuous integration
  • release.yml - Release automation

Technology Stack ​

Runtime ​

  • Vue 3.5+
  • Vue Router (latest)
  • @unhead/vue (head management)
  • TanStack Query (data fetching)
  • Pinia (state management, optional)
  • Tailwind CSS (styling, optional)

Build & Development ​

  • Vite 8.0-beta
  • TypeScript 5.9.3
  • Turborepo 2.7.5
  • tsdown 0.20.0-beta.3
  • pnpm 10.28.0

Code Quality ​

  • oxlint 1.42.0
  • oxfmt 0.27.0
  • Vitest 4.0.17
  • Changelogen 0.6.2

Parsing & AST ​

  • OXC (Oxide Compiler) - For JavaScript/TypeScript parsing
  • Used in: auto-import scanner, component registry, route generation

Performance Metrics ​

Package Size (from Repomix Analysis) ​

Top 5 Files by Token Count:

  1. packages/kit/src/vite/plugin.ts - 12,003 tokens (3.2%)
  2. docs/content/configuration.md - 7,810 tokens (2.1%)
  3. packages/router-generator/src/route-merger.test.ts - 7,019 tokens (1.9%)
  4. packages/kit/src/types/config.ts - 6,687 tokens (1.8%)
  5. plans/260128-layout-loader-suspense/phase-04-runtime-suspense.md - 6,647 tokens (1.8%)

Total Codebase ​

  • 418 files across all directories
  • 372,030 tokens (code + docs)
  • 1,497,767 characters
  • No suspicious files (security check passed)

Monorepo Workspace Layout ​

kimesh/
├── packages/*              # Core packages (11)
│   ├── kimesh             # Root/aggregator
│   ├── kit                # Build engine
│   ├── cli                # CLI
│   ├── router-generator   # Route generation
│   ├── router-runtime     # Runtime router
│   ├── auto-import        # Auto-import system
│   ├── head               # Meta/SEO
│   ├── query              # Data fetching
│   ├── layers             # Config layers
│   ├── create-kimesh      # Scaffolder
│   └── [others]
├── modules/*              # Official modules (3)
│   ├── pinia              # State management
│   ├── shadcn             # Component library
│   └── tailwindcss        # CSS framework
├── tooling/*              # Development tools
├── playground/apps/*      # Example apps
└── docs/                  # Documentation (VitePress)

Workspace Management: pnpm workspaces with monorepo protocol (workspace:*)

References ​

  • VitePress Config: docs/.vitepress/config.ts
  • Package Manager Config: pnpm-workspace.yaml
  • Build Config: turbo.json
  • Type Checking: tsconfig.json
  • Test Config: vitest.config.ts

Released under the MIT License.

Copyright © 2024-2026 Kimesh Contributors