# Upgrade to Angular 21 - Step by Step Guide

## Current Status
- **Current**: Angular 20.3.x
- **Target**: Angular 21.0.0

## Method 1: Automated Update (Recommended)

### Step 1: Backup Your Work
```bash
# Commit current changes
git add .
git commit -m "Backup before Angular 21 upgrade"
```

### Step 2: Run Angular Update Command
```bash
# Use Angular's interactive update tool
npx @angular/cli@21 update @angular/core@21 @angular/cli@21
```

This command will:
- Analyze your project
- Show what will be updated
- Automatically update dependencies
- Run code migrations
- Update `package.json` and `package-lock.json`

### Step 3: Follow the Prompts
- Review the changes it will make
- Confirm when prompted
- Let it run migrations automatically

## Method 2: Manual Update

### Step 1: Update Angular CLI First
```bash
npm install -g @angular/cli@21
```

### Step 2: Update All Angular Packages
```bash
npm install @angular/core@21 @angular/common@21 @angular/compiler@21 \
  @angular/forms@21 @angular/platform-browser@21 @angular/router@21 \
  @angular/compiler-cli@21 @angular/build@21 @angular/cli@21
```

### Step 3: Update Dev Dependencies
```bash
npm install --save-dev angular-eslint@21 ng-packagr@21
```

### Step 4: Update Library Peer Dependencies
Edit `projects/ccl-ui-components/package.json`:
```json
{
  "peerDependencies": {
    "@angular/common": "^21.0.0",
    "@angular/core": "^21.0.0"
  }
}
```

### Step 5: Install Dependencies
```bash
npm install
```

### Step 6: Run Migrations
```bash
ng update @angular/core @angular/cli --migrate-only
```

## Quick One-Liner (Automated)

```bash
# Backup, update, and test
git add . && git commit -m "Backup before Angular 21" && \
npx @angular/cli@21 update @angular/core@21 @angular/cli@21 && \
npm run build:lib && npm test
```

## After Upgrading

### 1. Update Library Peer Dependencies
Update `projects/ccl-ui-components/package.json`:
```json
"peerDependencies": {
  "@angular/common": "^21.0.0",
  "@angular/core": "^21.0.0"
}
```

### 2. Test Everything
```bash
# Build the library
npm run build:lib

# Run tests
npm test

# Test demo app
cd examples/angular-demo
npm install
npm start
```

### 3. Check for Breaking Changes
- Review console for deprecation warnings
- Check Angular 21 release notes: https://github.com/angular/angular/blob/main/CHANGELOG.md
- Review migration guide: https://update.angular.io/

## Troubleshooting

### If Update Fails
```bash
# Clear cache and retry
rm -rf node_modules package-lock.json .angular/cache
npm install
npx @angular/cli@21 update @angular/core@21 @angular/cli@21
```

### If Build Fails
```bash
# Check TypeScript version (Angular 21 needs TS 5.6+)
npm install typescript@latest --save-dev

# Check RxJS version
npm install rxjs@latest

# Rebuild
npm run build:lib
```

### If Tests Fail
```bash
# Update test dependencies
npm install --save-dev @types/jasmine@latest jasmine-core@latest karma@latest

# Clear test cache
rm -rf .angular/cache
npm test
```

## Verification Checklist

After upgrade, verify:
- [ ] `npm run build:lib` succeeds
- [ ] `npm test` passes
- [ ] `npm start` works (if you have a dev server)
- [ ] Demo app runs: `cd examples/angular-demo && npm start`
- [ ] No TypeScript errors: `npm run lint`
- [ ] Bundle analysis works: `npm run perf:analyze`

## Rollback (If Needed)

```bash
# Restore from git
git checkout package.json package-lock.json
npm install

# Or full rollback
git reset --hard HEAD
npm install
```

---

**Recommended**: Use Method 1 (Automated) as it handles migrations automatically.