# Local Development

> Running functions and web app locally, troubleshooting emulator issues, Storybook. Use when running or debugging locally.

- Skill: `diegosouzapw/local-development` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add diegosouzapw/local-development`
- Raw SKILL.md: https://api.skillmd.com/api/skills/diegosouzapw/local-development/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: diegosouzapw (https://skillmd.com/u/diegosouzapw)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/diegosouzapw/local-development

---


# Local Development

## When to Use

Use this skill when running the web app or functions locally, troubleshooting emulator issues, or running Storybook.

## Important

The user runs functions and web app locally for testing. Claude writes code and creates PRs -- Claude does NOT deploy or run dev servers.

## Running Functions Locally (user runs this)

```bash
npx nx run functions:serve
```

This command:
1. Builds the functions
2. Copies `.env.dev` to `dist/apps/functions/.env`
3. Starts watch mode for rebuilds (background)
4. Runs `firebase serve --only functions --project=dev` on port 5001

## Running Web App Locally (user runs this)

```bash
npx nx run maple-spruce:serve
```

Runs on http://localhost:3000

## Running Storybook

```bash
npx nx run maple-spruce:storybook
# Opens http://localhost:6006
```

Building Storybook:
```bash
npx nx run maple-spruce:build-storybook
# Output: dist/storybook/maple-spruce
```

## Running Tests

```bash
npm test
```

## Deployment

User decides when to deploy to dev. Production deploys automatically via CI/CD on merge to main.

## Troubleshooting Local Functions

### Emulator prompts for environment variables

The Firebase emulator is not finding the `.env` file. This happens when:
- The build clears `dist/apps/functions/` before the `.env` is copied
- A stale watch process is interfering

**Fix:**
```bash
# Kill any stale processes
pkill -f "firebase serve"
pkill -f "nx run functions"

# Clean and restart
rm -rf dist/apps/functions
npx nx run functions:serve
```

**Why this happens:**
- Firebase reads `.env` from `dist/apps/functions/`
- The `nx run functions:build` clears this directory
- The serve command copies `.env.dev` after build, before starting the emulator
- If ordering is wrong or stale processes exist, the emulator starts without the `.env`

**Key indicator it's working:**
```
i  functions: Loaded environment variables from .env.
```