Skip to main content

Local Development Setup

Get Kickstart running locally in a few minutes.

Prerequisites​

ToolVersionInstall
Node.js20+nodejs.org
Azure Functions Core Toolsv4Install guide
Azure OpenAI access—Request access

Setup​

1. Clone and install​

git clone https://github.com/sabbour/kickstart.git
cd kickstart
npm install

The root npm install installs dependencies for all workspace packages (packages/harness and packages/web).

2. Configure environment variables​

Create packages/web/api/local.settings.json:

{
  "IsEncrypted": false,
  "Values": {
    "FUNCTIONS_WORKER_RUNTIME": "node",
    "AzureWebJobsStorage": "",
    "AZURE_OPENAI_ENDPOINT": "https://your-resource.cognitiveservices.azure.com/",
    "AZURE_OPENAI_API_KEY": "your-api-key",
    "KICKSTART_CHAT_MODEL": "gpt-5.4-mini",
    "KICKSTART_CODEX_MODEL": "gpt-5.4",
    "KICKSTART_INSPIRE_MODEL": "gpt-5.4-nano"
  }
}

:::note Endpoint format For Azure AI Services (multi-service) resources, the endpoint uses .cognitiveservices.azure.com/. For legacy single-service Azure OpenAI resources, use .openai.azure.com/. Check your resource in the Azure Portal under Keys and Endpoint. :::

caution

Never commit local.settings.json files to source control. The repo already ignores them.

3. Start the development server​

npm run dev

This starts:

  • Vite dev server — React frontend with hot module replacement
  • SWA CLI — local Azure Static Web App emulator with functions

4. Open the app​

Navigate to http://localhost:4280 in your browser.

The SWA CLI proxies API requests from the frontend to the local Azure Functions runtime, matching the production Azure Static Web App behavior.

Dev Scripts​

ScriptDescription
npm run devFull-stack dev server (Vite + SWA CLI in parallel, port 4280)
npm run dev:viteVite dev server only (HMR, port 5173, no API)
npm run buildBuild all packages (core → web + mcp-server)
npm run api:buildBuild @kickstart/core + API only
npm testUnit/integration tests (vitest, all workspaces)
npm run test:e2ePlaywright E2E tests (headless)
npm run test:e2e:uiPlaywright E2E tests with interactive UI
npm run lintESLint across all TypeScript packages

Running Tests​

Unit and integration tests (vitest)​

# All workspaces
npm test

# Specific workspace
npm test -w @kickstart/core
npm test -w @kickstart/mcp-server

Or directly with vitest for more control:

npx vitest run            # run once
npx vitest watch          # watch mode
npx vitest run --coverage # with coverage

The root vitest.config.ts collects tests from all packages/*/src/**/__tests__/*.test.ts files and excludes Playwright specs.

End-to-end tests (Playwright)​

npm run test:e2e       # headless
npm run test:e2e:ui    # with Playwright UI (trace viewer, time-travel debugging)

E2E tests use their own dev server on port 4281 — they don't conflict with the SWA CLI dev server on port 4280.

Build Commands​

# Build everything (recommended)
npm run build

# Build individual packages
npm run build -w @kickstart/core
npm run build -w @kickstart/web
npm run build -w @kickstart/mcp-server
npm run api:build   # core + API (for deployment)

Build order matters: @kickstart/core must be built before the web API and MCP server because they reference it via TypeScript project references.

Frontend-Only Development​

When working on React components without needing the API:

npm run dev:vite

The app opens at http://localhost:5173 with HMR. It detects the API is unavailable and falls back to demo mode automatically (yellow "Demo" badge in the chat header).

MCP Server Development​

npm run build -w @kickstart/core
npm run build -w @kickstart/mcp-server

# Run via stdio (for testing with an MCP client)
node packages/mcp-server/dist/index.js

See MCP Tools for connecting to VS Code Copilot or Claude Code.

Dev Container​

The repo ships a .devcontainer configuration. Open in a GitHub Codespace or VS Code Dev Container for a pre-configured environment:

  1. Codespace: Click Code → Codespaces → New codespace
  2. VS Code: Open the repo, then Ctrl+Shift+P → Dev Containers: Reopen in Container

The container installs all dependencies, builds packages, and starts npm run dev automatically. Ports forwarded: 4280 (SWA CLI) and 5173 (Vite).

Infrastructure (Bicep)​

# Validate
az bicep build --file infra/main.bicep

# Dry run
az deployment group what-if \
  --resource-group rg-kickstart-dev \
  --template-file infra/main.bicep \
  --parameters @infra/parameters.dev.json

# Deploy
az deployment group create \
  --resource-group rg-kickstart-dev \
  --template-file infra/main.bicep \
  --parameters @infra/parameters.dev.json

See Deployment Guide for the full infrastructure and CI/CD setup.

Common Issues​

Functions not starting​

Make sure Azure Functions Core Tools v4 is installed:

func --version
# Should output 4.x.x

OpenAI errors​

Verify your local settings file is present and both deployment names match real Azure OpenAI deployments in your resource.