Builders, plugin and CLI

The entry points of the new engine: its Vite plugin, its Vite builders, the ng-doc command line interface, the schematics and the environment switches. Dev server and builds explains how they run.

Entry points

Vite plugin

Import the plugin from the built entry points of @ng-doc/builder:

import { createNgDocAngularPlugins } from '@ng-doc/builder/generator/vite/angular/index.js';
import { createNgDocVitePlugin } from '@ng-doc/builder/generator/vite/index.js';

createNgDocVitePlugin(options)

Returns the Vite plugins that run the new engine inside the Vite development server and build.

Generator options

All paths are absolute.

createNgDocApplicationPlugin(options)

Returns the Vite plugin that builds and serves the Angular application the way the Angular CLI application builder does. Relative paths are relative to workspaceRoot.

Other options of an angular.json build target fail with NGDOC_VITE_APPLICATION_OPTION, which names their Vite or Analog equivalent. allowedCommonJsDependencies, budgets, extractLicenses, namedChunks, optimization, outputHashing, progress, sourceMap, statsJson and verbose only log a warning. vite build sets ngDevMode and ngJitMode to false in every mode, unless the Vite define sets them.

createNgDocAngularPlugins(options)

Returns the Analog Angular plugins in the configuration that NgDoc supports. It accepts the options of @analogjs/vite-plugin-angular, except that liveReload must stay true, and jit, disableTypeChecking and fastCompile must stay false.

Limitations

• vite build --watch is not supported. Use the development server.
• The development server needs file watching and hot module replacement. Don't disable server.watch or server.hmr.

Vite builders

@ng-doc/builder:vite-application and @ng-doc/builder:vite-dev-server run a Vite configuration for ng build and ng serve. Paths are relative to the workspace root.

The NgDoc options, such as progress and generator.discovery.tags, come from the Vite plugin in the configuration file. Without generator.discovery.tags, the build tags are the mode (Pages and categories [Build tags]).

Command line interface

The ng-doc command generates the documentation without Angular CLI or Vite. Use it in scripts and in custom hosts.

ng-doc generate --project <project-name>
ng-doc dev --project <project-name> -- <command> [arguments]
ng-doc prerender --vite-config <file> --output-path <folder>

Paths are relative to the workspace root. --help prints the usage, and --version prints the version.

With a command after --, ng-doc dev exits with that command's exit code.

Schematics

The page, category and API schematics create files in the current folder. Pass --path to use another folder.

migrate-to-vite moves a project from the legacy builders to the Vite engine. It writes a report to .ng-doc-migration/<project-name>/report.md, and --dry-run shows the changes without writing them.

Environment switches

The new engine reads these variables in every entry point. Each one turns off one optimization. Use them to find the cause of a problem, and report it (Troubleshooting).

Production builds always use a fresh compiler worker, whatever these variables say.

Supported versions

The Vite engine is tested with Vite 8.3.2, Analog 2.8.0 and Angular 22.1 and 22.2. It checks the Vite version when it starts and stops with NGDOC_VITE_VERSION outside ^8.3.0. ng add and migrate-to-vite add these ranges to devDependencies when package.json doesn't list them, so npm installs the newest matching releases.

@ng-doc/builder takes @angular/build >=22.0.0 <23.0.0 as a peer dependency, the project's own copy, and depends on @angular-devkit/core >=22.0.0 <23.0.0 and @angular-devkit/architect >=0.2200.0 <0.2300.0, which the package manager shares with the project where it can: both engines run on the project's Angular 22 release. The Vite engine stops with NGDOC_VITE_ANGULAR_VERSION when the @angular/build it finds and @angular/compiler-cli come from different sides of Angular 22.2. The optional peer dependencies admit any Angular 22 for the Angular compilers, Analog ^2.8.0, and for vite Analog's own range (^6.0.0 || ^7.0.0 || ^8.0.0), so that installing NgDoc never fails on the Vite that Angular 22.0 or 22.1 brings before the migration adds Vite 8.3. NgDoc bundles its own patched copy of Analog's Angular plugin; the installed one supplies its types. The legacy builders don't use Vite or Analog.