Local Development Setup
Relevant source files
The following files were used as context for generating this wiki page:The Kiro project is a multi-faceted system designed to assist developers, comprising a web application, a Model Context Protocol (MCP) server, and a unique "Steering Document" system. This guide provides instructions and context for setting up the local development environment for these components. The setup involves standard procedures for a modern web application and a Kiro-specific configuration for contextual AI guidance.
The core of the Kiro development philosophy involves using structured specifications and steering documents to guide AI-assisted development. Understanding how to create and manage these documents is a key part of the local setup.
Sources: kiro-web-app/README.md, kiro-web-app/src/pages/SystemDocs.tsx:3-10
System Architecture Overview
The local development environment consists of several key parts that work together. The kiro-web-app provides the user interface, while the MCP Server handles backend logic. The Steering Documents provide persistent, contextual instructions to the Kiro AI assistant during development.
The following diagram illustrates the main components of the development environment.
Kiro Web App Setup
The kiro-web-app is a modern web application that serves as the primary interface for the Kiro Specification-Driven Development Guide.
Sources: kiro-web-app/README.md:1-3
Tech Stack
The web application is built with the following technologies:
| Layer | Technology | Purpose |
|---|---|---|
| UI Framework | React 18 | User interface framework |
| Language | TypeScript | Type safety |
| Styling | Tailwind CSS | Styling framework |
| Routing | React Router | Routing management |
| Icons | Lucide React | Icon library |
| Build Tool | Vite | Development server and build tool |
Sources: kiro-web-app/README.md:32-39
Setup and Commands
To set up the web application for local development, follow these steps. The process uses npm for dependency management and running scripts.
This diagram shows the setup flow for the web application.
Sources: kiro-web-app/README.md:43-50
The following commands are available in the package.json file for managing the application lifecycle.
| Command | Description |
|---|---|
npm install | Installs all project dependencies. |
npm run dev | Starts the development server, typically at http://localhost:3000. |
npm run build | Builds the application for production. |
npm run preview | Previews the production build locally. |
Sources: kiro-web-app/README.md:43-58
Kiro Steering Documents
A crucial part of the Kiro development environment is the "Steering Document" system. These are contextual guidelines located in the .kiro/steering/ directory of a workspace that influence how the Kiro AI assistant approaches development tasks. They contain project-specific standards, conventions, and best practices.
Sources: skills/create-steering-documents/SKILL.md:20-23, kiro-web-app/src/pages/SystemDocs.tsx:32-35
Structure and Location
Steering documents are Markdown files placed within the .kiro/steering/ directory at the root of your project.
.kiro/steering/
├── project-standards.md
├── git-workflow.md
├── frontend-standards.md
└── development-environment.md
Sources: skills/create-steering-documents/SKILL.md:144-151
Inclusion Logic
Steering documents use YAML front-matter to control when they are included in the AI's context.
inclusion Value | fileMatchPattern | Description |
|---|---|---|
always (or omitted) | Not applicable | The document is included in every interaction with the AI. |
fileMatch | Required (glob pattern) | The document is included only when files matching the pattern are part of the context. |
manual | Not applicable | The document is only included when explicitly referenced by the user. |
Sources: skills/create-steering-documents/SKILL.md:26-32, skills/create-steering-documents/SKILL.md:153-157, kiro-web-app/src/pages/SystemDocs.tsx:37-43
Core Document: development-environment.md
A key steering document for local setup is development-environment.md. It defines standards for the local development environment, environment variables, database management, and build processes. It is typically configured to be included when configuration files like package.json or Dockerfile are in context.
Sources: skills/create-steering-documents/SKILL.md:38-41, skills/create-steering-documents/SKILL.md:107-110
Below is the standard template for this file.
---
inclusion: fileMatch
fileMatchPattern: 'package.json|requirements.txt|Dockerfile|docker-compose.yml'
---
# Development Environment Setup
## Local Development
- Use Node.js version specified in .nvmrc file
- Install dependencies with `npm ci` for consistent builds
- Use Docker for local database and service dependencies
- Run linting and formatting before committing changes
## Environment Variables
- Copy `.env.example` to `.env` for local development
- Never commit actual environment files
- Document all required environment variables in README
- Use different prefixes for different environments (DEV_, PROD_, etc.)
## Database Management
- Use migrations for all schema changes
- Include rollback scripts for migrations
- Seed data should be idempotent
- Backup database before major changes
## Build and Deployment
- Ensure builds are reproducible across environments
- Use multi-stage Docker builds for optimization
- Include health checks in containerized applications
- Document deployment procedures and rollback steps
## Debugging and Logging
- Use structured logging with appropriate log levels
- Include correlation IDs for request tracing
- Set up proper error monitoring and alerting
- Use debugger instead of console.log for development
Sources: skills/create-steering-documents/SKILL.md:107-142, commands/create-steering-documents-standalone.md:139-174
Model Context Protocol (MCP) Server
The MCP (Model Context Protocol) Server is another component of the Kiro system. It can be configured using mcp.json files. The server can be enabled or disabled, and specific tools can be set to be auto-approved. The server automatically reconnects when its configuration changes.
Sources: kiro-web-app/src/pages/SystemDocs.tsx:55-65
Conclusion
Setting up a local development environment for the Kiro system involves two main activities: preparing the standard web application and understanding and configuring the project-specific steering documents. The kiro-web-app follows a conventional Vite + React setup process. The steering documents, particularly development-environment.md, are a unique aspect of the Kiro workflow, providing essential context to the AI assistant to ensure development aligns with project standards. A properly configured environment with well-defined steering documents is key to leveraging the full power of Kiro's spec-driven, AI-assisted development methodology.
Sources: skills/create-steering-documents/SKILL.md:20-23, kiro-web-app/README.md:41-50