Running the app

Everything you need to know about running postman-app locally — commands, flags, channels, and config.

---

The two-terminal workflow

Running the app always requires two terminals:

# Terminal 1 — start the dev server
yarn run start

# Terminal 2 — open the app (wait for Terminal 1's build to finish first)
yarn run open

yarn run start builds the app and serves it. yarn run open launches the Electron window pointing to that server. Both must stay running while you develop.

---

Webpack vs Rspack

The repo supports two bundlers:

Command	Bundler	When to use
yarn run start / yarn run open	Webpack	Default — most stable, used in CI
yarn start / yarn open	Rspack	Faster builds — the team is moving here

For day-to-day development, either works. Rspack (the shorter command) is faster and is the long-term direction.

---

Build targets: desktop vs browser

By default, the app builds for desktop (Electron). To build the web browser version instead:

yarn start --target browser
yarn open --target browser

The browser version runs in Chrome without Electron — useful for testing web-specific behavior or working on features that ship to postman.com.

---

Channels

Postman ships as multiple named apps: dev, beta, canary, stage, and prod. The channel controls which environment URLs and app icons are used. Use the -c flag to switch:

yarn run start -c dev      # default — dev backend (postman-beta.com)
yarn run start -c stage    # staging backend
yarn run start -c beta     # beta channel

# Packaging uses the same flag:
yarn run starship-package -c beta    # packages the PostmanBeta.app binary
yarn run starship-package -c prod    # packages the production Postman.app

Channel configs live in starship/ — one JSON file per channel. They define the app name, icon, URL protocol, and build directory.

---

Useful start flags

Skip slow modules

The console and runner modules add significant build time. If your work doesn't touch them, skip them:

yarn run start -- --skip-bundle="console,runner"

This is one of the most useful flags for fast iteration.

Analyze bundle size

yarn run start -- --analyze-bundle

Opens a visual bundle analyzer in the browser showing what's in each chunk. Useful for investigating why a PR increased bundle size.

Check duplicate packages

yarn run start -- --check-duplicates

Prints all duplicate npm packages in the bundle. Enabled by default in non-dev channels.

Disable hot module replacement

yarn run start -- --disable-hmr

Code still rebuilds on changes, but the app doesn't auto-reload. You'll need to press Cmd/Ctrl+R in DevTools manually. Useful when HMR is causing unexpected state issues.

---

Opening DevTools

# Open DevTools for all windows (except loader)
yarn run open -- --dev-tools

# Open DevTools for specific windows only
yarn run open -- --dev-tools=requester,loader
yarn run open -- --dev-tools=loader,shared,console

Available window keys: runner, console, requester, loader, shared.

note

--dev-tools works on the built app, not during dev mode (yarn run start). In dev mode, you can open DevTools manually via the app menu.

---

The configuration system

Environment-specific config (API gateway URLs, feature flags, service endpoints) lives in:

config/environments/
├── default/              # Standard Postman builds
│   ├── browser/
│   │   ├── base.json     # Shared defaults across all channels
│   │   ├── dev.json      # Dev channel overrides
│   │   ├── stage.json
│   │   └── prod.json
│   └── desktop/
├── gw/                   # Gateway variant (different service URLs)
│   └── browser/
├── enterprise/           # Enterprise / Postman Black builds
│   └── desktop/
└── local.json            # Your local overrides (gitignored — see below)

The three config types are:

• default — standard postman-app builds
• gw — gateway-specific service URLs (used by some internal tools)
• enterprise — enterprise and Postman Black builds

The active config is determined at runtime by domain/app context. The --channel flag selects which channel overlay to apply on top of base.json.

Overriding config locally

Create config/environments/local.json to override any config value during local development. This file is gitignored — your changes won't be committed:

{
  "__WP_CLOUD_AGENT_GATEWAY_WEBSOCKET_URL__": "'ws://localhost:8080/ws'"
}

This is the right way to point the app at a local backend service without modifying tracked files.

---

Test commands

# Run everything (lint + unit + system)
yarn run test

# Lint only
yarn run test-lint

# Unit tests with coverage
yarn run test-unit -- --coverage

# Tests for a specific file
yarn run test -- -f testFile.js

# Single Nx package
nx test @postman-app/workspace-data
nx lint @postman-app/workspace-data

---

Cleanup

# Remove all node_modules directories and build artifacts (dist/, build/, build-agent/)
yarn run clean

# Remove only local caches (.build-cache, .cachelint, .jest-cache, .nx)
yarn run clean-cache

Run yarn run clean when dependencies feel broken or after major branch switches. Run yarn run clean-cache when builds feel stale but dependencies are fine.

---

Quick reference

What you want	Command
Start dev server	yarn run start
Open the app	yarn run open
Faster builds	yarn start + yarn open
Web version	yarn start --target browser + yarn open --target browser
Skip console & runner	yarn run start -- --skip-bundle="console,runner"
Check bundle size	yarn run start -- --analyze-bundle
Open DevTools on start	yarn run open -- --dev-tools=requester
Point to staging	yarn run start -c stage
Package the app	yarn run starship-package -c dev
Run all tests	yarn run test
Clean everything	yarn run clean