Docusaurus Plugin
Relevant source files
The following files were used as context for generating this wiki page:
The @nx-extend/docusaurus plugin integrates the Docusaurus documentation framework into an Nx workspace. It provides specialized generators and executors to automate the creation, development, and production building of documentation sites within a monorepo environment.
The plugin enables hot-reloading during development, production optimizations, and full Nx integration including computation caching and dependency management. It also supports bundle analysis to visualize the size of Webpack output files.
Sources: packages/docusaurus/README.md:1-16, packages/docusaurus/package.json:1-10
Application Generation
The applicationGenerator function automates the setup of a new Docusaurus project. It normalizes project names, creates the directory structure, and configures Nx project targets.
Generation Workflow
The following diagram illustrates the steps taken by the generator when creating a new application:
The generator creates standard files including docusaurus.config.ts and updates workspace-level ignore files to exclude .docusaurus/ and .cache-loader/ directories.
Sources: packages/docusaurus/src/generators/application/generator.ts:74-135, e2e/docusaurus-e2e/tests/docusaurus.test.ts:12-19
Generator Options
| Option | Type | Default | Description |
|---|---|---|---|
name | string | - | The name of the documentation application. |
directory | string | apps | The directory where the project is placed. |
tags | string | - | Comma-delimited tags for linting. |
skipFormat | boolean | false | Skip automatic formatting of generated files. |
| Sources: packages/docusaurus/README.md:30-41, packages/docusaurus/src/generators/application/generator.ts:18-23 |
Project Configuration and Targets
The plugin configures two primary Nx targets for generated applications: build and serve. These targets map to specific executors provided by the @nx-extend/docusaurus package.
Target Definitions
{
"targets": {
"build": {
"executor": "@nx-extend/docusaurus:browser",
"options": {
"outputPath": "dist/apps/my-app"
}
},
"serve": {
"executor": "@nx-extend/docusaurus:dev-server",
"options": {
"port": 3000
}
}
}
}
Sources: packages/docusaurus/src/generators/application/generator.ts:98-115, packages/docusaurus/project.json:28-54
Dependencies
The generator adds the following core dependencies to the workspace package.json:
@docusaurus/core:3.4.0@docusaurus/preset-classic:3.4.0@mdx-js/react:^3.0.0reactandreact-dom:^18.0.0
Sources: packages/docusaurus/src/generators/application/generator.ts:118-126, packages/docusaurus/package.json:34-44
Build and Serve Executors
The plugin provides two main execution flows for interacting with Docusaurus sites: a development server and a production builder.
Development Server (Serve)
The serve target starts a Docusaurus development server with hot-module replacement. It supports options for port (default 3000), host (default localhost), and open to launch the browser automatically.
Sources: packages/docusaurus/README.md:44-55, packages/docusaurus/src/generators/application/generator.ts:109-113
Production Build (Build)
The build target generates a static production-ready website. By default, it minifies JavaScript bundles and places them in the specified outputPath.
The build process produces standard assets including index.html and sitemap.xml.
Sources: packages/docusaurus/README.md:58-71, e2e/docusaurus-e2e/tests/docusaurus.test.ts:22-30
Build Options
| Option | Type | Default | Description |
|---|---|---|---|
outputPath | string | - | The path for the output directory relative to workspace root. |
minify | boolean | true | Minimizes JavaScript bundles for production. |
bundleAnalyzer | boolean | false | Enables Webpack bundle analyzer treemap. |
| Sources: packages/docusaurus/README.md:65-71, packages/docusaurus/src/generators/application/generator.ts:104-106 |
Troubleshooting and Monorepo Workarounds
Docusaurus users in monorepos may encounter errors related to terser resolutions. This occurs because of dependency conflicts in nested node_modules.
Terser Resolution
If build errors occur, add a resolutions block to the root package.json (for Yarn users):
{
"resolutions": {
"terser": "^4.0.0"
}
}
Sources: packages/docusaurus/README.md:73-95
The @nx-extend/docusaurus plugin streamlines Docusaurus management by wrapping standard Docusaurus CLI commands into Nx-native generators and executors, ensuring consistent configuration across documentation projects.
Sources: packages/docusaurus/README.md:7-14, packages/docusaurus/generators.json:4-12