Skip to content
Tutorials Center
My learning

Topics

Lesson 54 of 74 ยท Tooling and Ecosystem

Project Structure and Best Practices

Organize an Angular app by feature, follow a consistent naming style, split smart and presentational components, turn on strict mode and lint rules, and keep upgrades painless.

Angular does not force a folder layout. A small app works with everything in src/app, and the same app with 80 components and five developers becomes a maze. Structure is not decoration: it decides how easily a newcomer finds code, how safely you can delete a feature and how quickly a refactor goes.

This lesson gives a practical default: group by feature, name things consistently, separate components that fetch from components that display, keep the compiler strict, let ESLint enforce conventions and use the upgrade tooling so you never fall far behind. None of this is law. Pick conventions and apply them everywhere.

Real versus stand-in. The folder trees, typescript, json and bash blocks are real Angular tooling output and configuration, read-only. The runnable examples are small stand-ins written in plain TypeScript: a dependency-rule checker and a naming checker. Real teams use ESLint plugins and tools such as Nx or dependency-cruiser for this job.

Organize by feature, not by file type

A beginner layout groups files by kind: all components in one folder, all services in another. It looks tidy, but a single change touches four folders. Group by what the code is for:

TEXT
src/app/
  app.ts                  root component
  app.config.ts           providers (router, http, ...)
  app.routes.ts           top-level routes
  core/                   app-wide singletons used once
    auth/                 auth service, interceptors, guards
    layout/               header, footer, shell
  shared/                 reusable, feature-agnostic building blocks
    ui/                   button, card, dialog (presentational)
    pipes/
    utils/
  features/
    products/
      product-list/       one folder per component
      product-detail/
      products.routes.ts  lazy-loaded routes of this feature
      product-api.ts      data access for this feature only
    cart/
    checkout/

The three top-level ideas are:

  • core: things created once for the whole app (auth, interceptors, the layout shell).
  • shared: small, generic, reusable pieces that know nothing about any feature (UI components, pipes, helper functions).
  • features: vertical slices. Everything about products lives in products/: its pages, its components, its data access and its routes.

Each feature maps to a lazily loaded route (Child Routes and Lazy Loading), so a feature folder also becomes a bundle boundary. Deleting a feature means deleting a folder.

Three rules keep this layout healthy, and they are all about the direction of imports:

flowchart TD
  F1["features/products"] --> C["core"]
  F2["features/cart"] --> C
  F1 --> S["shared"]
  F2 --> S
  C --> S
  F1 -. "not allowed" .-> F2
  S -. "not allowed" .-> F1

Dependencies point downward: features may use core and shared, shared depends on nothing above it, and features never import each other.

  1. shared imports nothing from core or features.
  2. A feature may import core and shared, but not another feature. If two features need the same thing, move it into shared or core.
  3. core may use shared, but never a feature.

Nothing in TypeScript enforces this, so teams add a check. This stand-in is a toy version of what a lint rule does:

TypeScript A dependency-rule checker

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

Smart and presentational components

Within a feature, split components by responsibility:

  • A smart (container) component knows about the outside world. It injects services, reads signals from a store, reacts to routes and passes data down.
  • A presentational (dumb) component receives everything through input() and reports everything through output() (Inputs and Outputs). It does not inject services that load data, so it is easy to reuse, test and preview.
TypeScript
@Component({
  selector: 'app-product-list-page',
  imports: [ProductCard],
  template: `
    @for (p of store.products(); track p.id) {
      <app-product-card [product]="p" (add)="store.addToCart(p.id)" />
    }
  `,
})
export class ProductListPage {
  protected readonly store = inject(ProductStore);
}

@Component({
  selector: 'app-product-card',
  template: `
    <h3>{{ product().name }}</h3>
    <button type="button" (click)="add.emit()">Add to cart</button>
  `,
})
export class ProductCard {
  product = input.required<Product>();
  add = output<void>();
}

The page knows the store; the card knows nothing except its input and its output. This is the same one-way data flow you saw earlier, applied to a whole app.

Naming and style

The official style guide favors small, consistent rules over clever ones: files named in lowercase kebab-case (product-list.ts), one concept per file, classes in PascalCase, selectors with a project prefix (app- or your own, so they never clash with HTML or other libraries), and folders that mirror features. Older projects and older generators name files with type suffixes such as product-list.component.ts and class names like ProductListComponent, and recent versions of the CLI generate shorter names without them. Either style is fine; mixing them is not. Check what your project already does and keep to it.

Other habits that pay off:

  • Use inject() for dependencies (Services and Dependency Injection) and readonly for injected fields.
  • Mark members used only by the template protected, and members used only inside the class private.
  • Keep templates small: move logic into computed() values instead of expressions in the HTML.
  • Prefer signals for state, OnPush-friendly immutable data and the new control flow (@if, @for).
  • Name event handlers for what they do (save, selectProduct), not what triggered them (onClick).

The next stand-in checks a few of these naming rules: a file name should be kebab-case, the class name should match the file name (with an optional suffix) and the selector should use the project prefix.

TypeScript A naming checker

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

Strict mode and linting

New projects start with strict TypeScript and strict templates, and you should keep them on. In tsconfig.json:

JSON
{
  "compilerOptions": {
    "strict": true,
    "noImplicitOverride": true,
    "noPropertyAccessFromIndexSignature": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true
  },
  "angularCompilerOptions": {
    "strictTemplates": true,
    "strictInjectionParameters": true,
    "strictInputAccessModifiers": true
  }
}

strict turns on TypeScript's null checks and implicit-any errors (TypeScript covers them). strictTemplates type-checks your templates, so a typo in a property or a wrong input type fails the build instead of showing up in front of a user. Turning strictness on late is hard (hundreds of errors at once), so start strict.

For conventions the compiler cannot see, add angular-eslint:

Terminal
ng add angular-eslint
ng lint

The plugin brings rules for components and templates. Examples include enforcing selector prefixes and casing, flagging empty lifecycle methods and preferring the built-in control flow in templates. Which rules are on, and what is recommended, changes between versions, so start from the recommended configuration it generates and tighten it deliberately. Run ng lint in CI so a convention is a failing check and not a code review comment.

Staying current with ng update

Angular ships a major version about every six months, and each release keeps the previous one supported for a limited time. Falling several versions behind turns an upgrade into a project. The CLI does most of the work:

Terminal
ng update                                   # shows what can be updated
ng update @angular/core @angular/cli        # updates the framework packages

ng update runs migrations: small automated code changes that rewrite your source for new APIs. Separately, the framework ships optional schematics that convert old patterns to modern ones, for example *ngIf and *ngFor to @if and @for, constructor injection to inject() and decorators to signal-based input() and output(). List and run them with the commands from the official update guide; run each one in a clean git working tree so you can review the diff. The official update guide at update.angular.dev gives version-specific steps. Update one major version at a time, run the tests after each step, and commit between steps.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why group code by feature instead of by file type?

    A feature folder holds its components, data access and routes, which makes it easy to find, change, lazy-load and remove.
  2. 2. Which import breaks the recommended layering?

    Dependencies should point from features toward core and shared. Shared code must not know about any feature.
  3. 3. What is the difference between a smart and a presentational component?

    Presentational components are driven entirely by inputs and outputs, so they are easy to reuse and test. Container components connect them to data.
  4. 4. What does strictTemplates add?

    With strictTemplates the compiler checks templates as carefully as TypeScript, so many bugs fail the build.
  5. 5. What is the safest way to upgrade across several Angular major versions?

    ng update runs migrations for each step. Doing one major at a time keeps each diff reviewable and problems easy to locate.

Summary

  • Organize by feature: core for app-wide singletons, shared for generic building blocks and features for vertical slices that map to lazy routes.
  • Keep imports pointing downward: features use core and shared, shared depends on nothing above it, and features never import each other. Enforce it with tooling.
  • Split smart components (services, state) from presentational ones (inputs and outputs only).
  • Choose one naming style and keep it everywhere; keep strict TypeScript and strictTemplates on and use angular-eslint in CI.
  • Use ng update regularly, one major version at a time, so migrations stay small.

Next: Building and Deploying.