Pi-Web Environments: Development vs. Production Configuration

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, missing translation warnings only appear during development to avoid console noise in production:

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 file implements optional password protection by reading PI_WEB_PASSWORD from the environment:

const password = process.env.PI_WEB_PASSWORD;

Host validation logic in lib/request-security.ts uses PI_WEB_HOSTNAME and PI_WEB_ALLOWED_HOSTS to restrict incoming requests to specific domains:

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, the code defaults to "0.0.0" during development but accepts production values from CI pipelines:

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:

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:

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 and 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.
• Custom PI_WEB_* variables (PI_WEB_PASSWORD, PI_WEB_HOSTNAME, PI_WEB_ALLOWED_HOSTS) provide server-side security controls implemented in proxy.ts and 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.
• 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, 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}