\r \r

Angular Frontend Development\r

\r

Project Structure\r

\r Standard Angular CLI layout:\r

src/\r
  app/\r
    app.module.ts          # Root module — declare ALL components here or import their modules\r
    app-routing.module.ts  # Root routing — define ALL top-level routes here\r
    app.component.ts       # Root component\r
    feature/\r
      feature.component.ts\r
      feature.component.html\r
      feature.component.css\r
  gallery/\r
    gallery.module.ts      # Feature module\r
    gallery.component.ts\r
```\r
\r
**Rule**: Components must live under `src/app/` (or a subdirectory) to be declared in `AppModule`. Components outside `src/app/` cannot be added to `AppModule` declarations.\r
\r
## Routing\r
\r
### Root vs Feature Module Routes\r
\r
**Root routing** (`AppRoutingModule`) — define ALL top-level routes here:\r
```typescript\r
const routes: Routes = [\r
  { path: '', redirectTo: '/users', pathMatch: 'full' },\r
  { path: 'users', component: UsersComponent },\r
  { path: 'comments', component: CommentsComponent },\r
  { path: 'gallery', component: GalleryComponent },\r
  { path: '**', redirectTo: '/users' }\r
];\r
```\r
\r
**Feature module routing** — `RouterModule.forChild([...])` in a feature module ONLY works if the module is lazy-loaded via `loadChildren`. If the feature module is eagerly imported in `AppModule`, routes defined in `forChild` are **silently ignored**.\r
\r
**Fix**: Either:\r
1. Move all routes to `AppRoutingModule` (simpler, recommended for small apps)\r
2. Use lazy loading: `{ path: 'gallery', loadChildren: () => import('./gallery/gallery.module').then(m => m.GalleryModule) }`\r
\r
### Common Routing Pitfalls\r
\r
- **Wildcard `**` route must be LAST** — order matters\r
- **`pathMatch: 'full'`** required on empty-path redirects, otherwise all routes match\r
- **Component not in declarations** — if a route points to a component not declared in any module, you get a runtime error (not a build error)\r
\r
## Modules\r
\r
### Declarations\r
\r
Every component, directive, and pipe must be declared in exactly ONE module:\r
```typescript\r
@NgModule({\r
  declarations: [\r
    AppComponent,\r
    UsersComponent,\r
    CommentsComponent  // Must be here if used in AppModule routes\r
  ],\r
  imports: [\r
    BrowserModule,\r
    AppRoutingModule,\r
    MatListModule,     // Material modules used in templates\r
    MatToolbarModule,\r
    MatButtonModule\r
  ]\r
})\r
```\r
\r
### Import Order\r
\r
When a component uses Material components in its template (e.g., `\x3Cmat-list>`, `\x3Cmat-toolbar>`), the corresponding `MatListModule`, `MatToolbarModule` etc. MUST be imported in the SAME module where the component is declared.\r
\r
## Components\r
\r
### Angular 18+ Defaults to Standalone Components\r
\r
**Angular 18+ generates standalone components by default.** If you're using NgModule pattern (non-standalone), you MUST add `standalone: false` to every component:\r
\r
```typescript\r
@Component({\r
  selector: 'app-users',\r
  templateUrl: './users.component.html',\r
  styleUrls: ['./users.component.css'],\r
  standalone: false    // ← REQUIRED when using NgModule declarations\r
})\r
export class UsersComponent {}\r
```\r
\r
Without `standalone: false`, you get `NG6008: Component is standalone, and cannot be declared in an NgModule`.\r
\r
### Creating a Component\r
\r
```bash\r
ng generate component feature-name\r
```\r
\r
This creates `feature-name.component.ts`, `.html`, `.css`, `.spec.ts` and adds it to the nearest module.\r
\r
### Component Outside `src/app/`\r
\r
If a component lives outside `src/app/` (e.g., `src/comments/`), it CANNOT be added to `AppModule`. Options:\r
1. Move it under `src/app/` (recommended)\r
2. Create a separate module for it and import that module\r
\r
## Services\r
\r
### Injectable Service\r
\r
```typescript\r
@Injectable({\r
  providedIn: 'root'  // Singleton, available everywhere\r
})\r
export class RestService {\r
  constructor(private httpClient: HttpClient) {}\r
}\r
```\r
\r
### HTTP Client\r
\r
Always import `HttpClientModule` in the root module (once):\r
```typescript\r
imports: [HttpClientModule]\r
```\r
\r
### Mock API Endpoints\r
\r
**reqres.in** now requires `x-api-key` header (returns 401 without it). Use **JSONPlaceholder** instead for free, no-auth mock data:\r
- `https://jsonplaceholder.typicode.com/users` — 10 users\r
- `https://jsonplaceholder.typicode.com/comments` — 500 comments\r
- `https://jsonplaceholder.typicode.com/posts` — 100 posts\r
\r
## TypeScript Configuration\r
\r
### moduleResolution for Angular 19+\r
\r
Angular 19 with TypeScript 5.7 requires `moduleResolution: "bundler"` in `tsconfig.json`:\r
\r
```json\r
{\r
  "compilerOptions": {\r
    "moduleResolution": "bundler",\r
    "module": "ES2022",\r
    "target": "ES2022"\r
  }\r
}\r
```\r
\r
Using the old `"moduleResolution": "node"` causes `TS2792: Cannot find module '@angular/core'`.\r
\r
## Common Build Errors\r
\r
| Error | Cause | Fix |\r
|-------|-------|-----|\r
| `NG6001: class is listed in declarations but is not a directive, component, or pipe` | Component file has wrong path or missing `@Component` decorator | Check import path, ensure `@Component` decorator is present |\r
| `NG6008: Component is standalone, and cannot be declared in an NgModule` | Angular 18+ defaults to standalone; missing `standalone: false` | Add `standalone: false` to `@Component` decorator |\r
| `TS2307: Cannot find module '@angular/core'` | Wrong `moduleResolution` in tsconfig | Set `moduleResolution: "bundler"` for TS 5.7+ |\r
| `TS2307: Cannot find module` | Wrong relative import path | From `src/app/comments/` to `src/app/rest/` use `../rest/rest.service` |\r
| `NG2003: No suitable injection token` | Service class not properly exported or `providedIn` missing | Add `@Injectable({ providedIn: 'root' })` |\r
| `error NG5002: Unexpected closing tag` | Duplicate closing tag in HTML template | Remove duplicate `\x3C/tag>` |\r
| `TS2307: Cannot find module 'rxjs'` | `rxjs` not installed after `node_modules` wipe | Run `npm install [email protected]` explicitly |\r
\r
## Template Pitfalls\r
\r
- **`mat-list-item` with multiple lines**: Use `matLine` directive on each line:\r
  ```html\r
  \x3Cmat-list-item *ngFor="let user of users">\r
    \x3Ch3 matLine>{{ user.name }}\x3C/h3>\r
    \x3Cp matLine>{{ user.email }}\x3C/p>\r
  \x3C/mat-list-item>\r
  ```\r
  Without `matLine`, only the first child is visible.\r
\r
- **`mat-list-item` height**: Default height clips multi-line content. Add CSS:\r
  ```css\r
  mat-list-item { height: auto !important; }\r
  ```\r
\r
- **Accessibility tree vs visual rendering**: `browser_snapshot` compact view may only show headings (h3) even when paragraphs (p) are present. Always use `full=true` to see all DOM content. The content IS there even if compact snapshot doesn't show it.\r
\r
## Build & Serve\r
\r
```bash\r
ng build                    # Production build\r
ng build --configuration development  # Development build\r
ng serve                    # Dev server on http://localhost:4200\r
ng serve --host 0.0.0.0    # Accessible from other machines\r
```\r
\r
## Angular Version Upgrades\r
\r
### Updating Angular CLI & Core\r
\r
Use the official update command:\r
```bash\r
npx @angular/cli@\x3Cversion> update @angular/core@\x3Cversion> @angular/cli@\x3Cversion> @angular/material@\x3Cversion>\r
```\r
\r
**⚠️ Don't jump more than 2-3 major versions at once.** Going from 16 → 22 in one step breaks: standalone components (default in 18+), TypeScript 6 requirement, `moduleResolution` changes, build system (`@angular/build` replaces `@angular-devkit/build-angular`). Safe path: 16 → 17 → 19 LTS.\r
\r
### After Updating package.json\r
\r
1. Delete `node_modules` and `package-lock.json`:\r
   - **Windows**: Must do this manually in PowerShell/CMD — the terminal tool gets blocked by EPERM:\r
     ```powershell\r
     Remove-Item -Recurse -Force node_modules\r
     Remove-Item -Force package-lock.json\r
     ```\r
2. Run `npm install`\r
3. If `rxjs` is missing: `npm install [email protected]`\r
4. Add `standalone: false` to all `@Component` decorators (Angular 18+)\r
5. Update `tsconfig.json` — set `moduleResolution: "bundler"` for TS 5.7+\r
6. Run `ng build --configuration development` to verify\r
\r
### Version Compatibility\r
\r
| Angular | Node (min) | TypeScript | zone.js | Standalone default |\r
|---------|-----------|------------|---------|-------------------|\r
| 16 | 16 | ~5.1 | ~0.13 | No |\r
| 17 | 18 | ~5.2-5.4 | ~0.14 | No |\r
| 18 | 18 | ~5.4-5.5 | ~0.14 | Yes |\r
| 19 LTS | 18 | ~5.5-5.7 | ~0.15 | Yes |\r
| 22 | 18 | ~5.8-6.0 | ~0.15 | Yes |\r
\r
**Key breaking changes per version:**\r
- **17**: New control flow syntax (`@if`/`@for`), but `*ngIf`/`*ngFor` still work\r
- **18**: Standalone components default; `NgModule` still fully supported with `standalone: false`\r
- **19**: TypeScript 5.7 requires `moduleResolution: "bundler"`; some Material APIs change\r
- **22**: New build system (`@angular/build`); TypeScript 6.x required; webpack builder deprecated\r
\r
### Reducing Dependabot Alerts\r
\r
Dependabot alerts in Angular projects often come from **dev dependencies** (build tools like `@angular-devkit/build-angular`, `esbuild`, `picomatch`, `tar`). These are NOT shipped to production. To reduce alerts:\r
1. Update Angular to latest LTS version\r
2. Run `npm audit` to check remaining vulnerabilities\r
3. Remaining alerts are typically in dev dependencies only — acceptable for school/lab projects\r
4. Across-repo alerts (e.g., `src/library/nodejs-server-generated/`) are in different sub-projects — check `package-lock.json` path in the alert to identify source\r
\r
For monorepo Dependabot patterns, see [references/dependabot-monorepo.md](references/dependabot-monorepo.md).\r
\r
## Docker Setup\r
\r
For production deployment, see [references/docker-setup.md](references/docker-setup.md) covering:\r
- Multi-stage Dockerfile (Node 22 → nginx Alpine)\r
- nginx.conf for SPA routing\r
- docker-compose.yml\r
- Common issues (Docker Desktop, peer deps, 404s)\r
\r
## Verification Checklist\r
\r
After making changes:\r
1. `ng build --configuration development` — must pass with 0 errors\r
2. `ng serve` — wait for "Compiled successfully"\r
3. Check each route in browser\r
4. Check browser console for runtime errors\r
5. Verify API calls return 200 (not 401/403)\r