# Pi-Web Environments: Development vs. Production Configuration

> Explore Pi-web environments: understand development vs. production modes and custom PI_WEB_* variables for secure server-side configuration and deployment.

- Repository: [Alex Yang/pi-web](https://github.com/agegr/pi-web)
- Tags: configuration
- Published: 2026-08-09

---

**Pi-web uses standard Next.js environment separation with `development` and `production` modes, augmented by custom `PI_WEB_*` environment variables for server-side security and deployment configuration.**

The `agegr/pi-web` repository is a Next.js application that implements distinct runtime behaviors for local development and production deployments. Understanding how pi-web environments are structured allows developers to leverage hot-reload workflows locally while ensuring secure, optimized builds for production servers.

## How Pi-Web Distinguishes Development and Production

### Build Commands and NODE_ENV Flags

Development mode launches via `npm run dev`, which initializes the Next.js development server on a dynamic port (e.g., `30141`) with hot-module replacement enabled. In this mode, `process.env.NODE_ENV` is automatically set to `"development"`.

Production mode requires `npm run build && npm start`, which generates optimized static and server-side rendering bundles in the `.next/` directory. After building, `process.env.NODE_ENV` is set to `"production"`, enabling aggressive caching and disabling development-specific diagnostics.

### Runtime Feature Toggles

The codebase conditionally enables debugging features based on the active environment. In [`lib/i18n/format.ts`](https://github.com/agegr/pi-web/blob/main/lib/i18n/format.ts), missing translation warnings only appear during development to avoid console noise in production:

```typescript
if (process.env.NODE_ENV !== "production") console.warn(`[i18n] Missing translation: ${key}`);

```

## Custom Environment Variables for Pi-Web Security

### Server-Side Protection Variables

Pi-web reads several `PI_WEB_*` prefixed variables at startup to enforce access controls. The [`proxy.ts`](https://github.com/agegr/pi-web/blob/main/proxy.ts) file implements optional password protection by reading `PI_WEB_PASSWORD` from the environment:

```typescript
const password = process.env.PI_WEB_PASSWORD;

```

Host validation logic in [`lib/request-security.ts`](https://github.com/agegr/pi-web/blob/main/lib/request-security.ts) uses `PI_WEB_HOSTNAME` and `PI_WEB_ALLOWED_HOSTS` to restrict incoming requests to specific domains:

```typescript
const allowed = [
  process.env.PI_WEB_HOSTNAME,
  ...(process.env.PI_WEB_ALLOWED_HOSTS?.split(",") ?? []),
];

```

### Public Version Configuration

The application exposes build version information through `NEXT_PUBLIC_APP_VERSION`, which is injected into the client bundle. In [`app/api/app-update/route.ts`](https://github.com/agegr/pi-web/blob/main/app/api/app-update/route.ts), the code defaults to `"0.0.0"` during development but accepts production values from CI pipelines:

```typescript
const CURRENT_VERSION = process.env.NEXT_PUBLIC_APP_VERSION ?? "0.0.0";

```

## Configuring Environment-Specific Behavior

Developers can implement conditional logic based on the current pi-web environment. To enable debug logging only during development:

```typescript
if (process.env.NODE_ENV === "development") {
  console.log("Running in development – extra diagnostics enabled");
}

```

To protect a local development server with basic authentication, set the variable before launching the dev server:

```bash
PI_WEB_PASSWORD=secret npm run dev

```

For production deployments, configure `PI_WEB_PASSWORD`, `PI_WEB_ALLOWED_HOSTS`, and `NEXT_PUBLIC_APP_VERSION` through your hosting platform's secret management system. These variables affect server-side behavior in [`proxy.ts`](https://github.com/agegr/pi-web/blob/main/proxy.ts) and [`lib/request-security.ts`](https://github.com/agegr/pi-web/blob/main/lib/request-security.ts) without exposing sensitive data to the client.

## Summary

- Pi-web uses **Next.js environment conventions** to separate development (`npm run dev`) from production (`npm run build && npm start`) execution contexts.
- The **`NODE_ENV`** environment variable controls feature toggles, such as i18n warning suppression in [`lib/i18n/format.ts`](https://github.com/agegr/pi-web/blob/main/lib/i18n/format.ts).
- **Custom `PI_WEB_*` variables** (`PI_WEB_PASSWORD`, `PI_WEB_HOSTNAME`, `PI_WEB_ALLOWED_HOSTS`) provide server-side security controls implemented in [`proxy.ts`](https://github.com/agegr/pi-web/blob/main/proxy.ts) and [`lib/request-security.ts`](https://github.com/agegr/pi-web/blob/main/lib/request-security.ts).
- **`NEXT_PUBLIC_APP_VERSION`** enables version tracking in production while defaulting to `0.0.0` during local development according to [`app/api/app-update/route.ts`](https://github.com/agegr/pi-web/blob/main/app/api/app-update/route.ts).
- Development mode serves assets directly from source with disabled caching, while production mode utilizes optimized static files from `.next/` with Next.js-managed cache headers.

## Frequently Asked Questions

### How do I start pi-web in development mode?

Run `npm run dev` to start the Next.js development server. This command selects a random available port, enables hot-module replacement, and sets `process.env.NODE_ENV` to `"development"` automatically.

### What environment variables are required for production deployments?

No variables are strictly required for the application to function, but production deployments should configure `PI_WEB_PASSWORD` for basic HTTP authentication and `PI_WEB_ALLOWED_HOSTS` to prevent host-header attacks. Set `NEXT_PUBLIC_APP_VERSION` to display accurate release information in the user interface.

### How does pi-web handle missing translations differently across environments?

In [`lib/i18n/format.ts`](https://github.com/agegr/pi-web/blob/main/lib/i18n/format.ts), the application logs console warnings for missing translation keys only when `process.env.NODE_ENV !== "production"`. Production builds suppress these diagnostics to improve runtime performance and reduce log noise.

### Can I use the password protection proxy during local development?

Yes, the [`proxy.ts`](https://github.com/agegr/pi-web/blob/main/proxy.ts) utility supports password protection in both development and production environments. Export `PI_WEB_PASSWORD` before running `npm run dev` to require authentication when accessing the local development server, mirroring the security controls used in deployed instances.