Skip to main content

New developer guide

Welcome to postman-app — the Postman desktop and web client. This is the repository that ships Postman to millions of developers around the world.

This guide gets you from a fresh machine to a running app and your first PR. Read it fully before touching code — it will save you hours later.

Before you start: get system access​

The private @postman NPM packages are gated. Without access, yarn install fails with 404s on every @postman/* package.

1. Join the @postman npm org. Request an invite from an NPM administrator. Membership matters: npm returns 404 (not 403) for private packages you cannot see, so no access looks exactly like bad auth.

2. Create a granular access token on npmjs.com under Settings → Access Tokens: grant Read on All packages and leave Organizations on No access (that dropdown is often empty; ignore it).

3. Authenticate Yarn with the token:

yarn config set -H npmAuthToken <YOUR_TOKEN>

npm login alone does not work: it writes ~/.npmrc, which Yarn v4 does not read. Treat the token as a secret.

The canonical reference is the NPM Registry page on Confluence.

Common install issues​

SymptomCause and fix
404 on every @postman/* packageYarn has no valid credential. Run yarn config set -H npmAuthToken <token> (not just npm login).
404s return after it worked beforeThe granular token expired. Regenerate it and re-run yarn config set -H npmAuthToken <token>.
404s persist with a fresh tokenA stray postman scope in ~/.yarnrc.yml routes @postman/* to the public mirror. Run yarn config get 'npmScopes[postman].npmRegistryServer'; if it prints registry.yarnpkg.com, delete that line so the scope falls back to the project default.

Also check the Prerequisite setup for local app development on Confluence — it covers SSL certificates and OS-level dependencies that vary by machine.

Setting up Node​

postman-app uses a specific Node version. Use NVM or N so you can switch versions cleanly:

# With NVM — run inside the repo root:
nvm use

# With N:
n auto

Both tools read .nvmrc / .n-node-version in the repo root and switch automatically. The app currently requires Node v24.

Running the app for the first time​

# 1. Clone
git clone git@github.com:postman-eng/postman-app.git
cd postman-app

# 2. Install dependencies (takes ~5-10 minutes the first time)
yarn install

# 3. In terminal 1 — start the dev server
yarn run start

# 4. In terminal 2 — open the app (after the build finishes)
yarn run open

The dev server starts at https://matrix.postman-beta.co:8777. You need two terminals running simultaneously — one for the server, one to open the Electron window.

One-time setup: local HTTPS certificate

The dev server runs over HTTPS, so on a fresh machine you 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

After that, yarn start generates a trusted certificate automatically (no need to create or commit one). Without it, the browser/Electron app blocks the page — postman-beta.co uses HSTS, so there is no "proceed anyway". See Prerequisite setup for local app development for full details.

Cloudflare WARP and SELF_SIGNED_CERT_IN_CHAIN

If yarn install or yarn open fails while building a native dependency with SELF_SIGNED_CERT_IN_CHAIN, Cloudflare WARP is intercepting the dependency downloads. On Node 24 the quickest fix is export NODE_USE_SYSTEM_CA=1, then re-run. See Running the app → Troubleshooting for the full explanation and fallback. This is a separate issue from the dev-server certificate above.

Hot module replacement (HMR) is enabled by default. Most code changes appear in the app without a restart.

Faster builds with Rspack

yarn run start uses Webpack. For faster builds, use:

yarn start    # Rspack dev server
yarn open     # Open the Rspack-built app
Building the web version
yarn start --target browser
yarn open --target browser

The 5 things to know before touching code​

1. Never add code to src/renderer/​

src/renderer/ is the legacy codebase — 19,000+ JavaScript files with no module boundaries. It runs in production but you must never add new code here. All new work goes into the Nx packages: views/, ui-features/, data/, platform-libs/, platform-ui/, or libs/.

When in doubt: ui-features/.

2. Dependencies only flow downward​

views/ → ui-features/ → data/ / platform-libs/ → libs/. A layer can import from below, never from above. The linter enforces this — violations fail CI.

3. Use the Nx generator to create packages​

Never create a package by hand. The generator creates the correct directory structure, project.json tags, and tsconfig paths automatically:

npx nx generate @postman/app-generator:library

4. Use @postman-app/* import aliases​

// ✅ Correct
import { WorkspaceStore } from '@postman-app/workspace-data';

// ❌ Wrong — never cross-package relative imports
import { WorkspaceStore } from '../../data/workspace-data/src';

5. apps/black is not production​

apps/black is an inactive proof-of-concept, not in the main CI or build pipeline. It is kept in the monorepo only to share code. The production entry point is src/renderer/.

Where is everything?​

Looking for…Go here
A UI feature (sidebar, modal, workbench tab)ui-features/<name>/
A URL-routed screenviews/<name>/
A Zustand store or API clientdata/<domain>-data/
i18n, analytics, API gatewayplatform-libs/<service>/
Design system componentsplatform-ui/aether-components/
Build configs, bundler setupconfig/
Environment URLs (dev/stage/prod)config/environments/
Electron packaging per channelstarship/
CI / automation scriptsscripts/
Translation stringslocales/en-US/
Legacy code (do not add to)src/renderer/

Running tests​

# Full check — lint + unit + system
yarn run test

# Lint only
yarn run test-lint

# Unit tests for a specific package
nx test @postman-app/workspace-data

# With coverage
yarn run test-unit -- --coverage

# Lint a specific package
nx lint @postman-app/workspace-data

# Clean all build artifacts and caches
yarn run clean
yarn run clean-cache

Unit tests live co-located with the code they test, inside each package's src/ directory.

Making your first PR​

# Branch from develop (not main)
git checkout develop && git pull
git checkout -b feat/your-feature-name

# After coding — check locally before pushing
nx lint @postman-app/your-package
nx test @postman-app/your-package
yarn typecheck:affected
# One lib: yarn nx run @postman-app/your-package:typecheck

# PR title format: [JIRA-TICKET] type(scope): description
# Example: [CSDK-1234] feat(workspace): add activity feed widget

Getting help​

  • Slack: #desktop-platform-eng for architecture questions, #client-distribution for CI/build
  • AGENTS.md in the repo root: coding conventions and architecture rules
  • Confluence spaces: Web Platform (WP) · Client Build and Release
  • Your onboarding buddy — ask them everything

Next steps​