Angular Components Development & Deployment Guide

Comprehensive guide for building, developing, and deploying the Angular CDK and Material Design component libraries.

Prerequisites

Node.js: Active LTS version (18.x or 20.x recommended)
Yarn: Classic stable version (1.22.x) - required for dependency management
Bazelisk: For managing Bazel versions (npm i -g @bazel/bazelisk)
Python: 3.9 or higher (required by Bazel build system)
Git: 2.x or higher
Optional:
- Google Cloud API key (for testing @angular/google-maps)
- YouTube Data API key (for testing @angular/youtube-player)

Installation

Clone the repository

git clone https://github.com/angular/components.git
cd components

Install dependencies
```
yarn install
```
Verify Bazel installation
```
bazel --version
```

Configuration

API Keys for Component Testing

For full functionality of map and video components, set environment variables:

export GOOGLE_MAPS_API_KEY="your-api-key-here"
export YOUTUBE_API_KEY="your-api-key-here"

Bazel Configuration (Optional)

Create .bazelrc.user in the project root for local build overrides:

# Limit resource usage
build --local_cpu_resources=HOST_CPUS*.5
build --local_ram_resources=HOST_RAM*.5

Build & Run

Development Server

Run the demo application to interact with components:

yarn dev-app

Or via Bazel directly:

bazel run //src/dev-app:devserver

Access at http://localhost:4200

Building Packages

Build all release packages (CDK, Material, Google Maps, YouTube Player, Aria):

yarn build

Output locations:

dist/releases/cdk/ - Component Dev Kit
dist/releases/material/ - Material Design components
dist/releases/google-maps/ - Google Maps integration
dist/releases/youtube-player/ - YouTube Player integration
dist/releases/aria/ - Accessibility utilities

Building Specific Packages

bazel build //src/cdk:npm_package
bazel build //src/material:npm_package
bazel build //src/material/schematics:schematics

Running Tests

Run all unit tests:

yarn test

Run tests for specific packages:

bazel test //src/cdk/tree/...
bazel test //src/material/autocomplete/...
bazel test //src/material/tooltip/...
bazel test //src/material/sidenav/...

Run tests with debugging:

yarn test --config=debug

Testing Schematics Locally

Test the Material Design 3 theme-color schematic:

# Build schematics
bazel build //src/material/schematics:schematics

# Run schematic (from project root)
bazel run //src/material/schematics:schematics -- generate theme-color --primary-color="#1976d2"

Deployment

Local Package Testing

Link built packages to a local Angular application for testing:

# Build all packages
yarn build

# Link packages globally
cd dist/releases/cdk && npm link
cd ../material && npm link
cd ../google-maps && npm link

# In your test Angular application
npm link @angular/cdk @angular/material @angular/google-maps

Production Build

Generate optimized release packages:

yarn build-release

Packages are output to dist/releases/ with proper package.json, type definitions, and ES modules.

(Maintainers) Publishing to npm

# Build and verify
yarn build

# Publish packages (requires npm permissions)
cd dist/releases/cdk && npm publish --access public
cd ../material && npm publish --access public
cd ../google-maps && npm publish --access public
cd ../youtube-player && npm publish --access public
cd ../aria && npm publish --access public

Troubleshooting

Bazel Build Failures

Cache corruption:

yarn bazel clean --expunge
rm -rf node_modules/.cache
yarn install

Out of memory errors: Add to .bazelrc.user:

build --local_ram_resources=4096
build --jobs=2

Windows-specific Issues

This repository requires a Unix-like environment. Use WSL2 (Ubuntu 20.04+) on Windows:

# In WSL2
sudo apt-get update
sudo apt-get install python3 python3-pip

Node Version Mismatches

Ensure correct Node version:

nvm use  # If .nvmrc exists
# or
nvm install 20
nvm use 20

Schematic Build Errors

If Material Design 3 theme-color schematic fails:

# Ensure dependencies are built
bazel build //src/material/schematics/ng-generate/theme-color:ng-generate_theme-color

Port 4200 Already in Use

yarn dev-app --port=4201
# or
bazel run //src/dev-app:devserver -- --port=4201

Dependency Issues

Clear caches and reinstall:

yarn cache clean
rm -rf node_modules yarn.lock
yarn install

How to Deploy & Use angular/components