What is @angular-devkit/core?
The @angular-devkit/core package is a fundamental part of the Angular DevKit which provides utility functions and an abstraction layer for managing file systems and other common tasks needed in the development of Angular applications. It is designed to be used by the Angular CLI and other tools to enhance and streamline the development process.
What are @angular-devkit/core's main functionalities?
Virtual File System
Allows manipulation of file systems in memory, which is useful for testing and build processes without affecting the actual file system.
{"import { virtualFs, HostTree } from '@angular-devkit/core';\nconst host = new HostTree();\nhost.create('/hello', 'world');\nconst exists = host.exists('/hello');\nconsole.log(exists); // true"}
Workspace Configuration
Provides utilities to read and manipulate Angular workspace configuration, enabling tools and scripts to modify project settings programmatically.
{"import { workspaces } from '@angular-devkit/core';\nasync function getWorkspace() {\n const workspaceHost = workspaces.createWorkspaceHost(host);\n const { workspace } = await workspaces.readWorkspace('/', workspaceHost);\n console.log(workspace.projects.get('my-app'));\n}"}
Schematics
Supports the creation and execution of schematics which are templates used to generate or transform projects. This feature is crucial for extending the Angular CLI's capabilities.
{"import { SchematicContext, Tree, Rule } from '@angular-devkit/schematics';\nfunction mySchematic(_options: any): Rule {\n return (tree: Tree, _context: SchematicContext) => {\n tree.create('hello.txt', 'Hello World');\n return tree;\n };\n}"}
Other packages similar to @angular-devkit/core
yeoman-generator
Similar to the schematics functionality of @angular-devkit/core, Yeoman generators allow the creation of projects or parts of projects through templates. However, Yeoman is more generic and not Angular-specific.
fs-extra
Provides extended functionality for the Node.js file system module, similar to the virtual file system capabilities of @angular-devkit/core, but operates on the actual file system rather than a virtual one.
webpack
While primarily a module bundler, webpack offers a rich plugin interface that can perform similar tasks to those of @angular-devkit/core, such as manipulating files and project assets. However, it is more focused on the build process rather than project scaffolding or configuration.
Core
Shared utilities for Angular DevKit.
Exception
Json
Schema
SchemaValidatorResult
export interface SchemaValidatorResult {
success: boolean;
errors?: string[];
}
SchemaValidator
export interface SchemaValidator {
(data: any): Observable<SchemaValidatorResult>;
}
SchemaFormatter
export interface SchemaFormatter {
readonly async: boolean;
validate(data: any): boolean | Observable<boolean>;
}
SchemaRegistry
export interface SchemaRegistry {
compile(schema: Object): Observable<SchemaValidator>;
addFormat(name: string, formatter: SchemaFormatter): void;
}
CoreSchemaRegistry
SchemaRegistry
implementation using https://github.com/epoberezkin/ajv.
Constructor accepts object containing SchemaFormatter
that will be added automatically.
export class CoreSchemaRegistry implements SchemaRegistry {
constructor(formats: { [name: string]: SchemaFormatter} = {}) {}
}
Logger
Utils
Virtual FS
Workspaces
The workspaces
namespace provides an API for interacting with the workspace file formats.
It provides an abstraction of the underlying storage format of the workspace and provides
support for both reading and writing. Currently, the only supported format is the JSON-based
format used by the Angular CLI. For this format, the API provides internal change tracking of values which
enables fine-grained updates to the underlying storage of the workspace. This allows for the
retention of existing formatting and comments.
A workspace is defined via the following object model. Definition collection objects are specialized
Javascript Map
objects with an additional add
method to simplify addition and provide more localized
error checking of the newly added values.
export interface WorkspaceDefinition {
readonly extensions: Record<string, JsonValue | undefined>;
readonly projects: ProjectDefinitionCollection;
}
export interface ProjectDefinition {
readonly extensions: Record<string, JsonValue | undefined>;
readonly targets: TargetDefinitionCollection;
root: string;
prefix?: string;
sourceRoot?: string;
}
export interface TargetDefinition {
options?: Record<string, JsonValue | undefined>;
configurations?: Record<string, Record<string, JsonValue | undefined> | undefined>;
builder: string;
}
The API is asynchronous and has two main functions to facilitate reading, creation, and modifying
a workspace: readWorkspace
and writeWorkspace
.
export enum WorkspaceFormat {
JSON,
}
export function readWorkspace(
path: string,
host: WorkspaceHost,
format?: WorkspaceFormat,
): Promise<{ workspace: WorkspaceDefinition }>;
export function writeWorkspace(
workspace: WorkspaceDefinition,
host: WorkspaceHost,
path?: string,
format?: WorkspaceFormat,
): Promise<void>;
A WorkspaceHost
abstracts the underlying data access methods from the functions. It provides
methods to read, write, and analyze paths. A utility function is provided to create
an instance of a WorkspaceHost
from the Angular DevKit's virtual filesystem host abstraction.
export interface WorkspaceHost {
readFile(path: string): Promise<string>;
writeFile(path: string, data: string): Promise<void>;
isDirectory(path: string): Promise<boolean>;
isFile(path: string): Promise<boolean>;
}
export function createWorkspaceHost(host: virtualFs.Host): WorkspaceHost;
Usage Example
To demonstrate the usage of the API, the following code will show how to add a option property
to a build target for an application.
import { NodeJsSyncHost } from '@angular-devkit/core/node';
import { workspaces } from '@angular-devkit/core';
async function demonstrate() {
const host = workspaces.createWorkspaceHost(new NodeJsSyncHost());
const { workspace } = await workspaces.readWorkspace('path/to/workspace/directory/', host);
const project = workspace.projects.get('my-app');
if (!project) {
throw new Error('my-app does not exist');
}
const buildTarget = project.targets.get('build');
if (!buildTarget) {
throw new Error('build target does not exist');
}
buildTarget.options.optimization = true;
await workspaces.writeWorkspace(workspace, host);
}
demonstrate();
18.0.0 (2024-05-22)
Breaking Changes
@angular/cli
- The
ng doc
command has been removed without a replacement. To perform searches, please visit www.angular.dev - Node.js support for versions <18.19.1 and <20.11.1 has been removed.
@angular-devkit/build-angular
-
By default, the index.html file is no longer emitted in the browser directory when using the application builder with SSR. Instead, an index.csr.html file is emitted. This change is implemented because in many cases server and cloud providers incorrectly treat the index.html file as a statically generated page. If you still require the old behavior, you can use the index
option to specify the output
file name.
"architect": {
"build": {
"builder": "@angular-devkit/build-angular:application",
"options": {
"outputPath": "dist/my-app",
"index": {
"input": "src/index.html",
"output": "index.html"
}
}
}
}
-
The support for the legacy Sass build pipeline, previously accessible via NG_BUILD_LEGACY_SASS
when utilizing webpack-based builders, has been removed.
Deprecations
@angular-devkit/schematics
NodePackageLinkTask
in @angular-devkit/schematics
. A custom task should be created instead.
@angular/cli
| Commit | Type | Description |
| --------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------- |
| ac3019570 | feat | add ng dev
alias to ng serve
|
| 4087728c3 | feat | support for Node.js v22 |
| 41ab6c8c3 | fix | add --version
option |
| df4dde95d | fix | add @angular/build
package to update group list |
| 1039f6d79 | fix | change update guide link to angular.dev |
| f4670fcb1 | fix | eliminate prompts during ng version
command |
| a99ec6a54 | fix | keep cli package first in update package group metadata |
| dd786d495 | fix | only add --version option on default command |
| 03eee0545 | refactor | remove ng doc
command |
| c7b208555 | refactor | remove support for Node.js versions <18.19.1 and <20.11.1 |
@schematics/angular
| Commit | Type | Description |
| --------------------------------------------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------- |
| b2ac5fac7 | feat | allow application migration to use new build package in projects where possible |
| 6530aa11b | feat | replace assets
with public
directory |
| 725883713 | feat | use eventCoalescing option by default (standalone bootstrap) |
| 508d97da7 | feat | use ngZoneEventCoalescing option by default (module bootstrap) |
| f452589e2 | feat | use TypeScript bundler module resolution for new projects |
| 95a4d6ee5 | fix | add less dependency in application migration if needed |
| c46aa084f | fix | add postcss dependency in application migration if needed |
| 157329384 | fix | add spaces around eventCoalescing option |
| 23cc337aa | fix | keep deployUrl option when migrating to application builder |
@angular-devkit/architect
| Commit | Type | Description |
| --------------------------------------------------------------------------------------------------- | ---- | ----------------------------------------------- |
| ddd08efef | fix | resolve builder aliases from containing package |
@angular-devkit/build-angular
| Commit | Type | Description |
| --------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------- |
| 53c319aaa | feat | add support for the poll
option in the library builder |
| 83d1d233a | feat | enhance Sass rebasing importer for resources URL defined in variables and handling of external paths |
| d51cb598a | feat | inject event-dispatch in SSR HTML page |
| 0b03829bc | feat | move i18n extraction for application builder to new build system package |
| 4ffe07aa2 | feat | move Vite-based dev-server for application builder to new build system package |
| d1c632af9 | feat | support native async/await when app is zoneless |
| 37fc7f0cc | fix | disable Vite prebundling when script optimizations are enabled |
| 2acf95a94 | fix | do not generate an index.html
file in the browser directory when using SSR. |
| 8a54875cb | fix | handle wrapping of class expressions emitted by esbuild |
| 97973059e | refactor | remove Sass legacy implementation |
@angular-devkit/schematics
| Commit | Type | Description |
| --------------------------------------------------------------------------------------------------- | -------- | ------------------------------- |
| 797584583 | refactor | deprecate NodePackageLinkTask
|
@angular/build
| Commit | Type | Description |
| --------------------------------------------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------ |
| 810d213e1 | feat | introduce new official build system package |
| b7a0792b3 | fix | add a maximum rendering timeout for SSG |
| 411115303 | fix | add console note about development server raw file size |
| 921fa7cf4 | fix | add missing ansi-colors
and picomatch
dependencies |
| 791cf75af | fix | check both potential build packages in Angular version check |
| 4d7cd5e3e | fix | correctly wrap class expressions with static properties or blocks emitted by esbuild |
| 57f448a0f | fix | decode URL pathname decoding during SSG fetch |
| 940e382db | fix | disable Vite prebundling when script optimizations are enabled |
| 70dbc7a6e | fix | emit error for invalid self-closing element in index HTML |
| 44b401747 | fix | ensure input index HTML file triggers rebuilds when changed |
| dff4deaeb | fix | ensure recreated files are watched |
| 17931166d | fix | format sizes using decimal byte units consistently |
| 2085365e0 | fix | only generate shallow preload links for initial files |
| 33cd47c85 | fix | properly configure headers for media resources and HTML page |
| d10fece2c | fix | properly rebase Sass url() values with leading interpolations |
| 3f2963835 | perf | add persistent caching of JavaScript transformations |
| a15eb7d1c | perf | improve rebuild time for file loader usage with prebundling |
<!-- CHANGELOG SPLIT MARKER -->
<a name="17.3.8"></a>