Skip to main content
This guide will help you set up your development environment to contribute to Angular Material and CDK.

​
Prerequisites

Node.js

Install Node.js (LTS version recommended)

pnpm

Package manager used by the project

Git

Version control system

Code Editor

VS Code or your preferred editor

​
Initial Setup

1

Install Node.js

We recommend using nvm to manage Node versions:
# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install and use LTS Node
nvm install --lts
nvm use --lts
2

Install pnpm

npm install -g pnpm
The project uses pnpm instead of npm for better performance and disk space efficiency.
3

Fork the repository

  1. Go to angular/components
  2. Click the “Fork” button
  3. Clone your fork:
git clone https://github.com/YOUR_USERNAME/components.git
cd components
4

Set up remotes

# Add upstream remote
git remote add upstream https://github.com/angular/components.git

# Verify remotes
git remote -v
Use upstream for angular/components and origin for your fork.
5

Install dependencies

pnpm install
This may take a few minutes on first run.

​
Windows Setup

Windows users should use Windows Subsystem for Linux (WSL).
1

Install WSL

Run as Administrator in PowerShell:
wsl --install
2

Restart your machine

After installation, restart Windows.
3

Enter WSL

wsl
You’re now in a Linux environment!
4

Continue with standard setup

Follow the installation steps above from within WSL.
For more details, see Microsoft’s WSL documentation.

​
Building the Project

​
Development Build

# Build all packages
pnpm build

# Output is in dist/releases/
ls dist/releases/

​
Development Server

Start the dev app with live reload: 
pnpm dev-app
The dev app will open at http://localhost:4200 and automatically reload on changes.
Browse Material components:
  • Navigate to http://localhost:4200
  • Select component from menu
  • Test different configurations

​
Running Tests

​
Unit Tests

# Test a single component
pnpm test button
pnpm test src/material/button
Use --debug to manually connect a browser to Karma for debugging.

​
E2E Tests

pnpm e2e

​
Linting

pnpm lint

​
Working with Public API

When making changes to public APIs:

​
Review API Changes

# After making changes
pnpm test:api
This compares your changes against golden files.

​
Approve API Changes

# Approve changes for a specific target
pnpm approve-api button

# Review the diff
cat goldens/material/button.api.md
Only approve intentional public API changes. These changes may be breaking!

​
Getting Build Artifacts

CI stores build artifacts for each PR:
1

Find the CI run

Go to the PR and click “Checks”
2

Navigate to artifacts

  1. Click on upload_release_packages job
  2. Switch to “Artifacts” tab
3

Download packages

Archives are named: <package>-pr<number>-<sha>.tgzExample:
{
  "dependencies": {
    "@angular/material": "https://circle-artifacts.com/.../material-pr12345-abc.tgz"
  }
}

​
Environment Variables

Optional environment variables for the dev app:

​
Google Maps API Key

# In .bashrc or .zshrc
export GOOGLE_MAPS_KEY=<your-api-key>
This enables Google Maps examples in the dev app.

​
Disabling Git Hooks

If you don’t want automatic commit validation: 
# In .bashrc or .zshrc
export HUSKY=0
This disables:
  • Commit message validation
  • Pre-commit formatting
Git hooks help maintain code quality but can be disabled for certain workflows.

​
Development Workflow

​
Typical Workflow

1

Create a branch

git checkout -b fix/button-ripple main
2

Start dev server

pnpm dev-app
3

Make changes

Edit source files - the dev app will auto-reload
4

Run tests

pnpm test button
5

Lint your code

pnpm lint
6

Build the project

pnpm build
7

Commit changes

git add .
git commit -m "fix(button): resolve ripple positioning issue"

​
Common Commands

# Full build
pnpm build

# Build specific package
pnpm build button

​
Troubleshooting

Increase Node memory:
export NODE_OPTIONS="--max-old-space-size=8192"
pnpm build
Clear caches:
# Clear node_modules
rm -rf node_modules
pnpm install

# Clear Angular cache
pnpm ng cache clean
Check port availability:
# Kill process on port 4200
lsof -ti:4200 | xargs kill -9

# Or use different port
pnpm dev-app -- --port 4201
Reinstall hooks:
pnpm husky install
Clone repo inside WSL filesystem (not /mnt/c):
# Good
cd ~
git clone ...

# Bad (slow)
cd /mnt/c/Users/...
git clone ...

​
IDE Setup

​
VS Code

Recommended extensions: 
{
  "recommendations": [
    "angular.ng-template",
    "esbenp.prettier-vscode",
    "dbaeumer.vscode-eslint",
    "stylelint.vscode-stylelint"
  ]
}

​
IntelliJ / WebStorm

  1. Enable TypeScript support
  2. Enable Angular support
  3. Configure Prettier as formatter
  4. Enable ESLint

​
Resources

Contributing Guide

How to contribute code

Coding Standards

Code style guidelines

GitHub Repo

Angular Components repository

Team Wiki

Internal team documentation

​
Getting Help

GitHub Discussions

Ask development questions

Gitter Chat

Real-time chat with team

Stack Overflow

Community Q&A

Discord

Angular community Discord

Build docs developers (and LLMs) love

Get started for freeTalk to us