Kimesh Project Overview & PDR

Version: 0.2.23 Status: Active Development Last Updated: January 28, 2026

Project Vision

Kimesh is a modern, type-safe Vue 3 full-stack framework designed to provide a seamless developer experience for building scalable web applications. It combines file-based routing, automatic code generation, and a modular architecture inspired by industry leaders like Nuxt.js and TanStack Router.

Mission Statement

Empower Vue developers to build type-safe, performant applications with minimal boilerplate through intelligent automation, clear conventions, and extensible plugin systems.

Target Users

1. Vue Developers - Teams using Vue 3 who want a batteries-included framework
2. Full-Stack Engineers - Developers building both client-side routing and server integration
3. Framework Authors - Those extending Kimesh with custom modules and plugins
4. Monorepo Teams - Organizations leveraging pnpm workspaces with shared component/config layers

Core Features

1. File-Based Routing

• Automatic route generation from file system structure
• Convention-based file patterns (e.g., $paramId.vue, __root.vue, _private-files.vue)
• Type-safe route generation with fully typed parameters
• Support for nested layouts and route groups

2. Build-Time Code Generation

• Two-phase build system (configuration loading → code generation)
• Automatic type generation for routes, components, and imports
• OXC-powered scanning for performance (100x faster than JavaScript)
• Hot Module Replacement (HMR) for development workflow

3. Plugin System

• Kit plugins for build-time extensibility
• Vite plugins for build integration
• Runtime plugins for app initialization
• Middleware pipeline for request/response handling

4. Modular Architecture

• Composable packages: kit, cli, router-generator, auto-import, head, query, layers
• Official modules: Pinia state management, Shadcn component registration, Tailwind CSS integration
• Layer system for configuration inheritance and monorepo scalability
• Automatic module discovery and installation

5. Developer Experience

• CLI commands: init, build, dev, generate, prepare, layer
• Auto-import system with intelligent component resolution
• SEO/Meta management (@unhead/vue integration)
• Data fetching abstraction (TanStack Query integration)
• Built-in debugging and error formatting

6. Type Safety

• Full TypeScript support with strict mode
• Generated route types with auto-completion
• Component type inference
• Query option type generation
• Runtime type validation

Technical Requirements

Core Dependencies

• Vue: 3.5+
• Vite: 8.0-beta+
• Vue Router: Latest
• TypeScript: 5.8+
• Node: 18+
• Package Manager: pnpm 10.28.0

Build Tools

• Turborepo: Task orchestration
• tsdown: TypeScript bundling
• oxlint/oxfmt: Rust-based linting and formatting (100x faster)
• Vitest: Testing framework with v8 coverage
• OXC (Oxide Compiler): AST parsing and scanning

Infrastructure

• GitHub Actions: CI/CD pipeline
• Monorepo: pnpm workspaces
• Release Automation: Changelogen for changelog management

Architecture Patterns

• Two-phase build: Configuration → Code Generation
• Plugin-based extensibility (Kit, Vite, Runtime)
• Layer-based configuration merging (c12, defu)
• Auto-import registry with conflict resolution
• Middleware pipeline for request handling

Functional Requirements

F1: Route Generation

• Auto-scan src/routes directory and generate route configuration
• Support nested routes, layouts, and dynamic parameters
• Generate TypeScript definitions for route parameters
• Maintain type safety across route transitions

F2: Component Resolution

• Auto-discover components in src/components
• Register components with auto-import system
• Support component name resolution strategies
• Integrate with OXC scanner for performance

F3: Build System Integration

• Two-phase Vite plugin lifecycle
• Phase 1: Config loading and route discovery
• Phase 2: Code generation and type generation
• Hot reload for development

F4: Data Loading

• TanStack Query integration for data fetching
• Route-level data loaders
• Query prefetching and caching
• Server-side data loading support

F5: Module System

• Automatic module discovery from modules/ directories
• Module registration and initialization
• Layer-based module override capabilities
• Module augmentation for type hints

F6: CLI Operations

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

F7: Configuration Management

• Declarative kimesh.config.ts format
• Layer-based config inheritance
• Environment-specific overrides
• Plugin configuration

F8: SEO & Meta Management

• Head component library
• Route-level meta configuration
• SEO utilities for common patterns
• Open Graph and JSON-LD support

Non-Functional Requirements

Performance

• Build time < 2s for typical projects
• Route generation O(n) complexity
• OXC-powered scanning (100x faster baseline)
• Zero-runtime overhead from generated code
• HMR updates < 500ms

Scalability

• Support monorepo projects with 50+ layers
• Handle 1000+ route definitions
• Auto-import registry with < 100ms resolution
• Efficient middleware pipeline

Reliability

• 95%+ test coverage for core packages
• TypeScript strict mode enforcement
• No runtime imports of build-time code
• Graceful error handling with detailed messages

Maintainability

• File size limit of 200 lines per file
• Clear separation of concerns in packages
• Comprehensive test coverage
• Well-documented API surface

Security

• No arbitrary code execution in plugins
• Safe template rendering in code generation
• Input validation for configuration
• Dependency vulnerability scanning

Success Metrics

Adoption

• Target: 5,000+ GitHub stars by v1.0
• Target: 1,000+ weekly npm downloads by v1.0
• Target: 100+ community modules by v1.0

Quality

• Maintain 90%+ test coverage
• Keep build times under 3s for typical projects
• Zero critical security vulnerabilities
• Resolution time for bugs < 48 hours

Developer Experience

• Time to first page load < 5 minutes
• 100% TypeScript coverage for framework code
• Complete API documentation
• 50+ example projects and tutorials

Stability

• Release cycle: Monthly minor releases
• LTS support for major versions
• Semantic versioning compliance
• Zero breaking changes in minor versions

Product Roadmap

Milestone 1: v0.3.0 (Q2 2026)

• Enhanced route merging for layouts
• Suspense boundary integration
• Improved error boundaries
• Performance optimizations

Milestone 2: v0.4.0 (Q3 2026)

• Island architecture support
• Streaming SSR capabilities
• Advanced caching strategies
• GraphQL integration

Milestone 3: v1.0.0 (Q4 2026)

• Stable API surface
• Production-ready features
• Comprehensive documentation
• Official plugin registry

Acceptance Criteria

• [ ] All core packages build successfully
• [ ] CLI commands execute without errors
• [ ] Test suite passes with > 90% coverage
• [ ] Documentation complete and accurate
• [ ] Performance benchmarks met
• [ ] No security vulnerabilities (CVSS > 0)
• [ ] Type generation produces valid TypeScript
• [ ] HMR works reliably in dev mode
• [ ] Production builds minimize bundle size
• [ ] Layer system supports inheritance chains

References

• Repository: https://github.com/kimeshjs/kimesh
• Package Registry: npm.js (@kimesh/*)
• Documentation: docs/content/
• Issues & Tracking: GitHub Issues
• Release Notes: docs/content/guides/releasing.md