# How to Run the Development Server and Tests for Pi Web: A Complete Guide

> Learn to run the Pi Web development server and execute tests with this complete guide. Easily get your Next.js UI for the pi coding agent up and running locally using npm commands.

- Repository: [Alex Yang/pi-web](https://github.com/agegr/pi-web)
- Tags: how-to-guide
- Published: 2026-08-14

---

**Pi Web is a Next.js browser UI for the *pi* coding agent that you run locally using `npm run dev` and test with `npm test`.**

This guide walks you through starting the development server and executing the test suite for Pi Web. The repository provides npm scripts that handle hot-reloading, type-checking, linting, and testing—all configured for rapid iteration on the browser interface.

## Starting the Pi Web Development Server

Pi Web ships with two development server modes defined in [`package.json`](https://github.com/agegr/pi-web/blob/main/package.json)【https://github.com/agegr/pi-web/blob/main/package.json#L31-L33】.

### Standard Local Development

The default `dev` script binds the Next.js server to **127.0.0.1:30141**:

```bash
npm install     # one-time setup

npm run dev     # http://127.0.0.1:30141

```

The server watches source files and rebuilds automatically on change. This mode is restricted to localhost for security during development.

### LAN Access Mode

For testing on other devices within your network, use the `dev:lan` script which binds to **0.0.0.0**:

```bash
npm run dev:lan

```

This exposes the same port (30141) to your local network while maintaining hot-reload functionality.

**Important:** According to [`AGENTS.md`](https://github.com/agegr/pi-web/blob/main/AGENTS.md)【https://github.com/agegr/pi-web/blob/main/AGENTS.md】, never run `next build` during active development—the development server handles compilation on demand.

## Running the Pi Web Test Suite

The `test` script executes Node's built-in test runner across all test files in the repository【https://github.com/agegr/pi-web/blob/main/package.json#L36-L38】:

```bash
npm test

```

This command:
- Discovers `*.test.mjs` files in `app/`, `components/`, `hooks/`, `lib/`, and `public/`
- Uses the experimental `--strip-types` flag to skip TypeScript declaration loading, improving execution speed
- Validates core logic including session handling, worktree management, and API routes

The test suite covers:
- **Session management** (`app/` and `lib/` modules)
- **UI components** (`components/` React code)
- **Client-side hooks** (`hooks/` like `useAgentSession` and `useAudio`)

## Additional Development Commands

### Type-Checking

Run the TypeScript compiler without emitting files (as documented in [`README.md`](https://github.com/agegr/pi-web/blob/main/README.md)【https://github.com/agegr/pi-web/blob/main/README.md#L21-L27】):

```bash
node_modules/.bin/tsc --noEmit

```

### Linting

Execute ESLint via the configured npm script:

```bash
npm run lint

```

The linting configuration uses `eslint-config-next` as specified in [`package.json`](https://github.com/agegr/pi-web/blob/main/package.json)【https://github.com/agegr/pi-web/blob/main/package.json#L62-L64】.

## Key Configuration Files

| File | Purpose |
|------|---------|
| [`package.json`](https://github.com/agegr/pi-web/blob/main/package.json) | Defines `dev`, `dev:lan`, `test`, and `lint` scripts【https://github.com/agegr/pi-web/blob/main/package.json】 |
| [`README.md`](https://github.com/agegr/pi-web/blob/main/README.md) | Quick-start documentation and workflow notes【https://github.com/agegr/pi-web/blob/main/README.md】 |
| [`AGENTS.md`](https://github.com/agegr/pi-web/blob/main/AGENTS.md) | Architecture overview and development server guidelines【https://github.com/agegr/pi-web/blob/main/AGENTS.md】 |

All commands assume execution from the repository root directory.

## Summary

- **Start developing:** Run `npm install` once, then `npm run dev` for localhost or `npm run dev:lan` for network access
- **Run tests:** Execute `npm test` to validate all `*.test.mjs` files using Node's native test runner
- **Quality checks:** Use `node_modules/.bin/tsc --noEmit` for type-checking and `npm run lint` for code quality
- **Port and host:** Default is 127.0.0.1:30141; LAN mode uses 0.0.0.0:30141

## Frequently Asked Questions

### What port does the Pi Web development server use?

The development server runs on **port 30141** for both `npm run dev` (localhost only) and `npm run dev:lan` (network accessible). This is hardcoded in the npm scripts within [`package.json`](https://github.com/agegr/pi-web/blob/main/package.json)【https://github.com/agegr/pi-web/blob/main/package.json#L31-L33】.

### Why does `npm test` use the `--strip-types` flag?

The `--strip-types` experimental flag prevents Node from attempting to load TypeScript declaration files at runtime. This results in faster test execution while still allowing TypeScript syntax in your test files, as implemented in the `test` script【https://github.com/agegr/pi-web/blob/main/package.json#L36-L38】.

### Can I run production builds during development?

No. According to [`AGENTS.md`](https://github.com/agegr/pi-web/blob/main/AGENTS.md)【https://github.com/agegr/pi-web/blob/main/AGENTS.md】, you should never run `next build` during active development. The development server (`npm run dev`) handles all compilation and hot-reloading automatically without requiring production builds.

### Where are the test files located in the Pi Web repository?

Test files use the `*.test.mjs` naming convention and are distributed across `app/`, `components/`, `hooks/`, `lib/`, and `public/` directories. The `npm test` command automatically discovers and executes all matching files.