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.

---

Prerequisite: local HTTPS certificate (mkcert)

The dev server serves the app over HTTPS at https://matrix.postman-beta.co:8777 (and :8778). That hostname is a public DNS record that already resolves to 127.0.0.1, so no /etc/hosts entry is needed.

The certificate is generated per machine via mkcert on yarn start — you just need mkcert installed and its local CA registered once:

# macOS
brew install mkcert nss && mkcert -install

# Windows
choco install mkcert && mkcert -install

# Linux: install libnss3-tools + the mkcert binary, then:
mkcert -install

mkcert -install is required because postman-beta.co uses HSTS — the browser/Electron app won't offer a "proceed anyway" bypass, so the certificate must be trusted (a plain self-signed cert is blocked). If you hit a NET::ERR_CERT_* warning, confirm mkcert -install has run, then delete npm/certs/*.pem and re-run yarn start to regenerate it.

---

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.

---

Troubleshooting

yarn install or yarn open fails with SELF_SIGNED_CERT_IN_CHAIN

You see one or more native dependencies fail to build, for example skia-canvas, @postman/starship, keytar, node-pty, @parcel/watcher, or macos-export-certificate-and-key, with an error like:

gyp ERR! stack FetchError: request to https://nodejs.org/download/release/v24.14.0/node-v24.14.0-headers.tar.gz failed, reason: self-signed certificate in certificate chain
  code: 'SELF_SIGNED_CERT_IN_CHAIN'

This is unrelated to the local dev-server certificate (mkcert). It happens because Cloudflare WARP inspects TLS traffic: during install, some dependencies download native binaries or Node/Electron build headers over HTTPS (from nodejs.org, electronjs.org, S3, or GitHub), and WARP re-signs that traffic with its own root CA. Node ships its own CA bundle and does not read the OS trust store by default, so it rejects the re-signed chain.

Fix: use the system trust store (recommended)

WARP already installs its root CA into the macOS keychain and the Windows certificate store, so the simplest fix is to tell Node to use the OS trust store. The app runs on Node 24, where this is built in (NODE_USE_SYSTEM_CA and the equivalent --use-system-ca flag ship in Node 23.8+):

export NODE_USE_SYSTEM_CA=1
yarn install   # or yarn open

Add the export line to your ~/.zshrc so it persists across sessions. This is the fix Node itself points to in its certificate-error hint, and it needs no .pem file. On macOS and Windows the WARP cert is already in the system store, so nothing else is required. On Linux, --use-system-ca reads OpenSSL's default CA paths rather than a single unified store, so results are less consistent there; if it does not work, use the fallback below.

Fallback: point Node at the WARP CA file

If the WARP root CA is not in your OS trust store, point NODE_EXTRA_CA_CERTS at the cert file directly:

export NODE_EXTRA_CA_CERTS="/Library/Application Support/Cloudflare/installed_cert.pem"
yarn install

That path is the macOS WARP cert location; ask in #it-help if you cannot locate it on your platform.

Both options keep Node's normal chain verification intact. Do not use NODE_TLS_REJECT_UNAUTHORIZED=0, which turns verification off entirely.

Scope: these settings only affect Node's own TLS. The app resolves all dependencies from the npm registry and prebuilt native binaries (no git+https dependencies), so the Node setting covers every download in a normal install. A dependency fetched over git+https, or a postinstall script that shells out to curl, git, or python, would use that tool's own CA handling and need separate configuration (for example git config --global http.sslCAInfo).

Why this only appears sometimes

An existing node_modules skips these download and build scripts, so the proxy interception stays invisible. A fresh clone, yarn run clean, or a branch switch that changes dependencies re-runs them, which is why the failure can surface unexpectedly even though the dependencies themselves have not changed.

---

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