Skip to content

Angular project setup: CLI, structure and standalone

Before you write a component, you need a workspace that builds, serves and tests itself. This page covers the three things every new Angular developer meets on day one: the Angular CLI that creates and runs the project, the files it generates and how to grow them into a maintainable folder structure, and the standalone component model that replaced NgModule as the way Angular apps are assembled.

Everything here is written against Angular 22 (@angular/core 22.2 and @angular/cli 22.2 at the time of writing). Angular 22 supports Node.js ^22.22.3, ^24.15.0 or ^26.0.0 and TypeScript >=6.0 <6.1, according to Angular’s version compatibility table. The running example is OrdersPortal, an invented order-management front end.

Topic What it covers
Angular CLI Installing ng, creating a workspace, serving, generating, building and testing
Project structure The generated files and a feature-based layout that scales
Standalone components and NgModules Why new code has no NgModule, and how to read code that still does

The Angular CLI is published on npm as @angular/cli and installs a binary named ng. It creates workspaces, generates code that follows the official style guide, runs the dev server, builds production bundles with the @angular/build:application builder (esbuild and Vite under the hood), runs unit tests, and applies version migrations through ng update.

ng new asks a few questions (stylesheet format, server-side rendering) and then writes a workspace. Generated code follows the current style guide: ng generate component order-list creates order-list.ts, order-list.html, order-list.css and order-list.spec.ts, with a class named OrderList. Older projects use the *.component.ts suffix; both work.

New workspaces run unit tests with Vitest in a Node.js environment with jsdom. Karma is still supported for existing projects. A new workspace has no lint target; the first ng lint offers to add one (angular-eslint).

The commands below are a terminal session, not run here (the sandbox cannot create a workspace); they follow the Angular CLI reference.

Terminal window
npm install -g @angular/cli@22 # or use npx @angular/cli@22 for one-off commands
ng version # confirm CLI, Angular and Node.js versions
ng new orders-portal # prompts for styles and SSR
cd orders-portal
ng serve # dev server on http://localhost:4200 with live reload
ng generate component orders/order-list # short form: ng g c orders/order-list
ng generate service orders/orders-api # short form: ng g s orders/orders-api
ng test # Vitest in watch mode
ng build # production build into dist/orders-portal/
ng update @angular/core @angular/cli # move to the next major, one major at a time

For a client-rendered app, ng build writes the deployable files to dist/orders-portal/browser/; copy that folder to any static host and configure it to fall back to index.html for deep links.

Pitfalls:

  • Hand-copying a component folder. Renaming a copied component means fixing the class name, selector, template and style paths and the spec by hand. ng generate gets all of them right in one step.
  • A global CLI that does not match the project. Inside a workspace, ng runs the project’s local CLI version, but a stale global install still runs ng new. Use npx @angular/cli@22 new to pin the version you mean.
  • Skipping majors with ng update. Migrations are written for one hop at a time. Go 20 to 21 to 22, committing after each.

ng new orders-portal creates a workspace folder. At its root are angular.json (build, serve and test configuration for every project in the workspace), package.json, tsconfig.json with tsconfig.app.json and tsconfig.spec.json, and a public/ folder whose files are copied as-is into the build output (favicons, robots.txt, images you do not import from code).

The application lives in src/. main.ts bootstraps the app, index.html is the host page and styles.css holds global styles. Inside src/app/, app.ts, app.html and app.css define the root component App, app.config.ts holds the application-wide providers, and app.routes.ts holds the route table.

The generated files are a starting point. As the app grows, the Angular style guide recommends organizing by feature area rather than by file type, keeping a component’s TypeScript, template, styles and spec side by side with the same base name, and separating words in file names with hyphens.

orders-portal/
β”œβ”€β”€ angular.json
β”œβ”€β”€ package.json
β”œβ”€β”€ public/
β”‚ └── favicon.ico
└── src/
β”œβ”€β”€ index.html
β”œβ”€β”€ main.ts # bootstrapApplication(App, appConfig)
β”œβ”€β”€ styles.css
└── app/
β”œβ”€β”€ app.ts / app.html / app.css / app.spec.ts
β”œβ”€β”€ app.config.ts # provideRouter(routes), provideHttpClient(...)
β”œβ”€β”€ app.routes.ts
β”œβ”€β”€ core/ # app-wide services, interceptors, guards
β”‚ └── auth-interceptor.ts
β”œβ”€β”€ shared/ # small reusable UI and pipes
β”‚ └── order-status.pipe.ts
└── orders/ # one folder per feature
β”œβ”€β”€ order-list.ts / order-list.html / order-list.css / order-list.spec.ts
β”œβ”€β”€ order-detail.ts
β”œβ”€β”€ orders-api.ts
└── orders.routes.ts # lazy-loaded child routes

A feature folder can be lazy-loaded as a unit (loadChildren: () => import('./orders/orders.routes')), which keeps the initial bundle small and gives each team an obvious place to work.

Pitfalls:

  • A flat components/ folder. It works for ten components and becomes unsearchable at fifty, because a feature’s component, service and tests are scattered across type folders.
  • A shared/ folder that becomes a junk drawer. Only put something in shared/ once a second feature uses it.
  • Importing from another feature’s internals. If billing/ reaches into orders/order-detail.ts, the two features can no longer be lazy-loaded or owned separately. Expose what other features need through a small public file or a service.

Since Angular 19, components, directives and pipes are standalone by default: each one lists what its template uses in its own imports array, and the application is bootstrapped from a root component with bootstrapApplication(). You no longer write standalone: true; it is implied.

NgModule was the original unit of composition. A module declared components, imported other modules and exported what other modules could use, and the app started from a root AppModule. Modules are still supported, and a lot of production code uses them, but for new code they are a compatibility and interop surface. A component that belongs to an NgModule must now say standalone: false.

The practical difference is where dependencies are visible. In a module, everything declared or imported is visible to every template in the module. A standalone component sees only what its own imports array lists. That makes dependencies explicit and lets the build drop unused code per component.

// main.ts: standalone bootstrap with no AppModule (fragment, from a generated app)
import { bootstrapApplication } from '@angular/platform-browser';
import { App } from './app/app';
import { appConfig } from './app/app.config';
bootstrapApplication(App, appConfig).catch((err) => console.error(err));
// app.config.ts
import { ApplicationConfig, provideBrowserGlobalErrorListeners } from '@angular/core';
import { provideRouter, withComponentInputBinding } from '@angular/router';
import { routes } from './app.routes';
export const appConfig: ApplicationConfig = {
providers: [provideBrowserGlobalErrorListeners(), provideRouter(routes, withComponentInputBinding())],
};
// order-card.ts: the component lists exactly what its template uses
import { Component } from '@angular/core';
import { CurrencyPipe } from '@angular/common';
@Component({
selector: 'app-order-card',
imports: [CurrencyPipe],
template: `<p>{{ 249.5 | currency: 'USD' }}</p>`,
})
export class OrderCard {}
// The same component in an NgModule-based app (legacy style)
// @Component({ selector: 'app-order-card', standalone: false, template: '...' })
// export class OrderCard {}
// @NgModule({ declarations: [OrderCard], imports: [CommonModule], exports: [OrderCard] })
// export class OrdersModule {}

The OrderCard component above was compiled with ngc (Angular 22.2.6, TypeScript 6.0.3, strictTemplates); it renders <p>$249.50</p>.

To migrate an existing app, run the official schematic in three passes, committing between them: ng generate @angular/core:standalone and choose Convert all components, directives and pipes to standalone, then Remove unnecessary NgModule classes, then Bootstrap the application using standalone APIs, checking that the app builds and runs after each pass.

Pitfalls:

  • Forgetting an import. A standalone template that uses | currency without CurrencyPipe (or CommonModule) in imports fails to compile with an unknown pipe error. Nothing is inherited from where the component is used.
  • Importing CommonModule out of habit. Built-in control flow (@if, @for) needs no import, so most new components need only the specific pipes they use.
  • Mixing the two models carelessly. A standalone component can import an NgModule and a module can import a standalone component, which makes gradual migration possible. Migrate leaf components first so the dependency graph shrinks from the bottom up.
  • Start every new app with ng new and standalone components; there is no reason to create an AppModule in Angular 22.
  • Keep the generated layout until a second feature exists, then move to feature folders with lazy-loaded routes.
  • In a module-based codebase, migrate with the standalone schematic instead of mixing hand-converted files with modules indefinitely.

What does ng generate component do that copying a folder does not? It creates the TypeScript, template, styles and spec with consistent names, a correct selector and class name, and it follows the workspace’s schematic defaults (style format, test runner, prefix). It also respects options in angular.json, so every generated component matches the project conventions.

What changed for standalone components in Angular 19? standalone became true by default, so new components, directives and pipes do not declare it. Components that must be declared in an NgModule now need standalone: false. Standalone APIs had been stable since Angular 15.

Where do application-wide providers live in a standalone app? In the providers array of the ApplicationConfig passed to bootstrapApplication(), usually in app.config.ts. Functions such as provideRouter() and provideHttpClient() replace the old RouterModule.forRoot() and HttpClientModule imports.

Why organize by feature rather than by file type? Related code changes together, so keeping a feature’s components, services and tests in one folder makes changes local, makes ownership clear and lets the feature be lazy-loaded as a unit.

Senior scenario: OrdersPortal is a 200-component NgModule app on Angular 18. How do you get it to Angular 22 and standalone? Upgrade first, one major at a time with ng update, running tests and committing after each hop, because the standalone migration is easier on a current version. Then run the standalone schematic per feature area: convert declarations, remove empty modules, and switch to bootstrapApplication last. Convert shared leaf components first, keep each step in its own reviewable commit, and use lazy routes (loadComponent, loadChildren) as features convert so bundle size improves along the way. Track remaining standalone: false components as the migration backlog.