Project structure

Understand the files and directories that make up an Angular workspace and how they work together.

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