@nx-plus/docusaurus

Nx Plus Docusaurus

First class support for Docusaurus in your Nx workspace.

Contents

• Prerequisite
• Getting Started
• Schematics (i.e. code generation)
• Builders (i.e. task runners)
• Updating Nx Plus Docusaurus
• Troubleshooting

Prerequisite

If you have not already, create an Nx workspace with the following:

npx create-nx-workspace@^15.0.0

Getting Started

Install Plugin

# npm
npm install @nx-plus/docusaurus --save-dev

# yarn
yarn add @nx-plus/docusaurus --dev

Generate Your App

nx g @nx-plus/docusaurus:app my-app

Serve Your App

nx serve my-app

Schematics (i.e. code generation)

Application

nx g @nx-plus/docusaurus:app <name> [options]

Arguments	Description
<name>	The name of your app.

Options	Default	Description
--tags	-	Tags to use for linting (comma-delimited).
--directory	apps	A directory where the project is placed.
--skipFormat	false	Skip formatting files.

Builders (i.e. task runners)

Dev Server

nx serve <name> [options]

Arguments	Description
<name>	The name of your app.

Options	Default	Description
--port	3000	Use specified port.
--host	localhost	Use specified host.
--hotOnly	false	Do not fallback to page refresh if hot reload fails.
--open	false	Open page in the browser.

Browser

nx build <name> [options]

Arguments	Description
<name>	The name of your app.

Options	Default	Description
--bundleAnalyzer	false	Visualize size of webpack output files with an interactive zoomable treemap.
--outputPath	-	The full path for the new output directory, relative to the current workspace.
--minify	true	Build website minimizing JS bundles.

Updating Nx Plus Docusaurus

Nx Plus Docusaurus provides migrations which help you stay up to date with the latest version of Nx Plus Docusaurus.

Not only do we migrate the version of Nx Plus Docusaurus, but we also update the versions of dependencies which we install such as @docusaurus/core and react.

We recommend waiting for Nx Plus Docusaurus to update these dependencies for you as we verify that these versions work together.

How to Migrate

Generate migrations.json

All you have to do to update Nx Plus Docusaurus to the latest version is run the following:

nx migrate @nx-plus/docusaurus
nx migrate @nx-plus/docusaurus@version # you can also specify version

This will fetch the specified version of @nx-plus/docusaurus, analyze the dependencies and fetch all the dependent packages. The process will keep going until the whole tree of dependencies is resolved. This will result in:

• package.json being updated
• migrations.json being generated

At this point, no packages have been installed, and no other files have been touched.

Now, you can inspect package.json to see if the changes make sense and install the packages by running npm install or yarn.

Run Migrations

migrations.json contains the transformations that must run to prepare the workspace to the newly installed versions of packages. To run all the migrations, invoke:

nx migrate --run-migrations=migrations.json

Troubleshooting

If you encounter this error while building a Docusaurus app, then you may need to add a terser resolution to your package.json. Note: this only works with Yarn and not npm.

Error:

Docusaurus user: you probably have this known error due to using a monorepo/workspace.
We have a workaround for you, check https://github.com/facebook/docusaurus/issues/3515

package.json:

{
  // ...
  "resolutions": {
    "terser": "^4.0.0"
  }
  // ...
}

Once this has been updated, you should be able to run yarn install and then build your Docusaurus application.