Skip to main content

Run your doc site in development

Docusaurus is a React-based project and uses npm and or Yarn project workflows. This page describes npm commands to start previews, lint, build, and do other necessary things in development.

note

Periodically run npm install before running Docusaurus to install or update dependencies.

npm commands and scripts​

The following is a list of npm scripts in package.json.

npm run start​

Runs Docusaurus locally on port http://localhost:3000 to preview the site. Supports automatic refresh when changes are made. This is usually used in development while making changes to Markdown or certain configuration files.

note

Not all changes made are supported by the automatic refresh and may require restarting the command.

npm run build​

Builds Docusaurus for production into the ./build directory of the root folder of this project.

It's usually not necessary to do this in development and is usually only used by CI when building to be deployed.

caution

There's an open issue regarding proper and stable CSS insertion ordering that may differ between npm run start and npm run build results.

This is usually not an issue and can be mitigated with adding !important to CSS styles.

npm run build:docs​

If you use the docusaurus-plugin-openapi-docs plugin for integrating OpenAPI to your docs, this command cleans existing generated Markdown API docs and re-generates them.

This command is bundled into the npm run build command.

You can safely remove this script from the package.json if you're not using the plugin.

npm run swizzle​

Swizzles a component. Swizzling allows more advanced customization of React components in Docusaurus beyond simple CSS modifications.

npm run deploy​

Deploys your Docusaurus project.

note

You don't need to use this command for your doc site.

npm run clear​

Removes all generated assets, caches, or build artifacts. If you have issues running npm run start, we recommend using this command.

npm run serve​

Serves the files generated by the build output from the ./build directory for local viewing. Run this after the npm run build command.

note

Since npm run build is for production building or debugging production build issues, you don't need to use npm runs serve except in those cases.

npm run write-translations​

Only needed where translations are to be added.

npm run write-heading-ids​

Only needed where translations are to be added.

npm run typecheck​

Typechecks with TypeScript and tsconfig.json.

npm run typecheck-staged​

Typechecks staged-only files which is used by lint-staged when committing.

npm run lint​

Combined command which includes spell check, JS/TS linting, and CSS linting.

npm run lint:js​

Lints JS/TS with ESLint.

npm run lint:spelling​

Checks spelling using CSpell.

Add new words to the dictionary

If you use a word in your content that's not known to the linter, your build or commit fails. If the word that the linter caught is correctly spelled, and you wish it to pass the linter's test, add it to project-words.txt.

npm run lint:style​

Lints CSS files with specific styling.

npm run lint:fix​

Passes the --fix CLI argument to npm run lint:js to attempt to fix issues.

npm run format​

Runs Prettier to format code before commit for consistency in the repo.