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 first thing you need is access to the private @postman NPM packages. Without this, yarn install will fail completely. Request an invite from a Postman NPM administrator, then log in from your terminal:

npm login

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.

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

# 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​