Project structure

Workspace structure

When you create a new Angular workspace with ng new, the CLI generates the following structure:

my-app/
├── .editorconfig
├── .gitignore
├── README.md
├── angular.json
├── package.json
├── tsconfig.json
├── tsconfig.app.json
├── tsconfig.spec.json
└── src/
    ├── favicon.ico
    ├── index.html
    ├── main.ts
    ├── styles.css
    └── app/
        ├── app.component.ts
        ├── app.component.html
        ├── app.component.css
        ├── app.component.spec.ts
        └── app.module.ts

Root configuration files

The workspace root contains essential configuration files for your project.

angular.json

The workspace configuration file defines build, serve, and test configurations:

angular.json

{
  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
  "version": 1,
  "newProjectRoot": "projects",
  "projects": {
    "my-app": {
      "projectType": "application",
      "sourceRoot": "src",
      "prefix": "app",
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "outputPath": "dist",
            "index": "src/index.html",
            "browser": "src/main.ts",
            "polyfills": ["zone.js"],
            "tsConfig": "tsconfig.app.json",
            "assets": ["src/favicon.ico", "src/assets"],
            "styles": ["src/styles.css"],
            "scripts": []
          }
        },
        "serve": {
          "builder": "@angular/build:dev-server",
          "options": {
            "buildTarget": "my-app:build"
          }
        }
      }
    }
  }
}

Key sections:

projects: Contains configuration for each application or library
architect: Defines builders for different tasks (build, serve, test)
options: Specifies paths, assets, styles, and build settings

package.json

The npm configuration file lists dependencies and scripts:

package.json

{
  "name": "my-app",
  "version": "0.0.0",
  "scripts": {
    "ng": "ng",
    "start": "ng serve",
    "build": "ng build",
    "test": "ng test",
    "lint": "ng lint"
  },
  "private": true,
  "dependencies": {
    "@angular/common": "^21.2.0",
    "@angular/compiler": "^21.2.0",
    "@angular/core": "^21.2.0",
    "@angular/forms": "^21.2.0",
    "@angular/platform-browser": "^21.2.0",
    "@angular/router": "^21.2.0",
    "rxjs": "^7.0.0",
    "tslib": "^2.3.0",
    "zone.js": "0.16.1"
  },
  "devDependencies": {
    "@angular-devkit/build-angular": "^21.2.0",
    "@angular/cli": "^21.2.0",
    "@angular/compiler-cli": "^21.2.0",
    "typescript": "~5.9.3"
  }
}

Key sections:

scripts: Convenient commands to run CLI commands
dependencies: Runtime packages required by your application
devDependencies: Development tools and build packages

Use npm start as a shortcut for ng serve to start the development server.

TypeScript configuration files

Angular uses multiple TypeScript configuration files for different contexts.

tsconfig.json

The base TypeScript configuration:

tsconfig.json

{
  "compileOnSave": false,
  "compilerOptions": {
    "outDir": "./dist/out-tsc",
    "sourceMap": true,
    "esModuleInterop": true,
    "declaration": false,
    "experimentalDecorators": true,
    "module": "es2022",
    "moduleResolution": "bundler",
    "importHelpers": true,
    "target": "es2022",
    "typeRoots": ["node_modules/@types"],
    "lib": ["es2018", "dom"]
  },
  "angularCompilerOptions": {
    "strictTemplates": true
  }
}

Important options:

experimentalDecorators: Enables decorators like @Component
module: Specifies module system (ES2022)
target: JavaScript version for output (ES2022)
strictTemplates: Enables strict type checking in templates

tsconfig.app.json

Extends base configuration for application builds:

tsconfig.app.json

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "./out-tsc/app",
    "types": []
  },
  "files": ["src/main.ts"],
  "include": ["src/**/*.d.ts"]
}

tsconfig.spec.json

Configuration for test files:

tsconfig.spec.json

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "./out-tsc/spec",
    "types": ["jasmine"]
  },
  "include": ["src/**/*.spec.ts"]
}

Other root files

.editorconfig

Defines consistent coding styles across different editors:

.editorconfig

root = true

[*]
charset = utf-8
indent_style = space
indent_size = 2
insert_final_newline = true
trim_trailing_whitespace = true

.gitignore

Specifies files and directories Git should ignore:

.gitignore

/node_modules
/dist
/tmp
/.angular

Source directory (src/)

The src/ directory contains your application code and assets.

src/index.html

The main HTML page that hosts your Angular application:

src/index.html

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>MyApp</title>
  <base href="/">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="icon" type="image/x-icon" href="favicon.ico">
</head>
<body>
  <app-root></app-root>
</body>
</html>

The <app-root> element is where Angular inserts your application.

src/main.ts

The application entry point that bootstraps the Angular application:

src/main.ts

import { platformBrowser } from '@angular/platform-browser';
import { AppModule } from './app/app.module';

platformBrowser()
  .bootstrapModule(AppModule)
  .catch((err) => console.error(err));

This file:

Imports the platform browser module
Imports the root application module
Bootstraps the application to run in the browser

src/styles.css

Global styles applied across your entire application:

src/styles.css

/* You can add global styles to this file */
html, body {
  margin: 0;
  padding: 0;
  font-family: Arial, sans-serif;
}

src/assets/

Directory for static assets like images, fonts, and files:

src/assets/
├── images/
│   └── logo.png
└── data/
    └── config.json

Files in this directory are copied as-is during the build process.

App directory (src/app/)

The application source code lives in the src/app/ directory.

Component files

Each component typically consists of four files:

app.component.ts

The component class containing logic:

src/app/app.component.ts

import { Component } from '@angular/core';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css'],
  standalone: false,
})
export class AppComponent {
  title = 'my-app';
}

app.component.html

The component template:

src/app/app.component.html

<h1>{{ title }}</h1>
<p>Welcome to your Angular app!</p>

app.component.css

Component-specific styles:

src/app/app.component.css

h1 {
  color: #1976d2;
  font-family: Arial, sans-serif;
}

app.component.spec.ts

Unit tests for the component:

src/app/app.component.spec.ts

import { TestBed } from '@angular/core/testing';
import { AppComponent } from './app.component';

describe('AppComponent', () => {
  beforeEach(async () => {
    await TestBed.configureTestingModule({
      declarations: [AppComponent],
    }).compileComponents();
  });

  it('should create the app', () => {
    const fixture = TestBed.createComponent(AppComponent);
    const app = fixture.componentInstance;
    expect(app).toBeTruthy();
  });
});

app.module.ts

The root module that defines the application structure:

src/app/app.module.ts

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule],
  providers: [],
  bootstrap: [AppComponent],
})
export class AppModule {}

Build and output directories

dist/

Generated by ng build, contains compiled application ready for deployment:

dist/
└── my-app/
    ├── index.html
    ├── main.js
    ├── polyfills.js
    ├── runtime.js
    ├── styles.css
    └── assets/

.angular/

Cache directory created by the Angular CLI to speed up builds:

.angular/
└── cache/

Both dist/ and .angular/ directories should be added to .gitignore and not committed to version control.

Multi-project workspaces

Workspaces can contain multiple projects (applications and libraries):

my-workspace/
├── angular.json
├── package.json
└── projects/
    ├── app1/
    │   └── src/
    ├── app2/
    │   └── src/
    └── shared-lib/
        └── src/

Create additional applications:

ng generate application app2

Create libraries:

ng generate library shared-lib

Next steps

Now that you understand the project structure, explore Angular’s core concepts.

Components

Build reusable UI components

Templates

Create dynamic HTML templates

Services

Share data and logic across components

Routing

Navigate between different views

Overview

Getting Started

Core Concepts

Routing & Navigation

Forms

HTTP & APIs

Advanced Topics

CLI & Tools

Best Practices

​Workspace structure

​Root configuration files

​angular.json

​package.json

​TypeScript configuration files

​tsconfig.json

​tsconfig.app.json

​tsconfig.spec.json

​Other root files

​.editorconfig

​.gitignore

​Source directory (src/)

​src/index.html

​src/main.ts

​src/styles.css

​src/assets/

​App directory (src/app/)

​Component files

​app.component.ts

​app.component.html

​app.component.css

​app.component.spec.ts

​app.module.ts

​Build and output directories

​dist/

​.angular/

​Multi-project workspaces

​Next steps

Components

Templates

Services

Routing

Build docs developers (and LLMs) love

Workspace structure

Root configuration files

angular.json

package.json

TypeScript configuration files

tsconfig.json

tsconfig.app.json

tsconfig.spec.json

Other root files

.editorconfig

.gitignore

Source directory (src/)

src/index.html

src/main.ts

src/styles.css

src/assets/

App directory (src/app/)

Component files

app.component.ts

app.component.html

app.component.css

app.component.spec.ts

app.module.ts

Build and output directories

dist/

.angular/

Multi-project workspaces

Next steps