mirror of
https://github.com/facebook/docusaurus.git
synced 2025-04-29 18:27:56 +02:00
30cf744544
* docs: add some details (trivial) * docs: add easier method (using yarn) to test local repo * docs: add additional note * Edits * Update Co-authored-by: Josh-Cena <sidachen2003@gmail.com>
83 lines
3.4 KiB
Markdown
83 lines
3.4 KiB
Markdown
Sometimes you want to test the latest version of Docusaurus on a third-party project via `npm` or `yarn` without having to publish it to npm itself. For example, you may want to use the latest code in `main`.
|
|
|
|
> If you want to use Docusaurus to test Docusaurus, see the [testing changes on Docusaurus itself doc](./testing-changes-on-Docusaurus-itself.md)
|
|
|
|
There are two reasonable ways to use a local version of the Docusaurus npm package to test changes you make to the Docusaurus core on a third-party project.
|
|
|
|
## Install from a local Docusaurus repo
|
|
|
|
### Install in an existing project
|
|
|
|
Let's say you have an existing project with this snippet inside package.json:
|
|
|
|
```json
|
|
{
|
|
"dependencies": {
|
|
"@docusaurus/core": "^2.0.0-beta.8",
|
|
"@docusaurus/preset-classic": "^2.0.0-beta.8"
|
|
}
|
|
}
|
|
```
|
|
|
|
Now, you have made changes to @docusaurus/core (this lives in packages/docusaurus) and would like to test the changes. In the local docusaurus repo, run `yarn install`. This will also build the local docusaurus packages and install them within the repo itself:
|
|
|
|
```sh
|
|
cd /path/to/local/docusaurus
|
|
# can use yarn build:packages if dependencies have not been modified
|
|
yarn install
|
|
```
|
|
|
|
In the existing project, add the local package:
|
|
|
|
```sh
|
|
cd /path/to/existing/project
|
|
# this can be an absolute or relative path
|
|
yarn add @docusaurus/core@../../local/docusaurus/packages/docusaurus
|
|
```
|
|
|
|
Check package.json again and you will find this:
|
|
|
|
```json
|
|
{
|
|
"dependencies": {
|
|
"@docusaurus/core": "../../local/docusaurus/packages/docusaurus",
|
|
"@docusaurus/preset-classic": "^2.0.0-beta.8"
|
|
}
|
|
}
|
|
```
|
|
|
|
If you make further changes to the local docusaurus repo, run `yarn install` inside the existing project so that the changes will be applied.
|
|
|
|
Note that:
|
|
|
|
- The format is `scoped-package-name@local/path/to/specific/package/directory`.
|
|
- The last component of the supplied path cannot be a symbolic link, it has to be the package directory itself.
|
|
- If you supplied the wrong directory name, `yarn add` may not complain, but `yarn build` and `yarn start` will fail. To avoid this, check `package.json` inside the package directory to make sure you have the correct path.
|
|
- These commands don't work:
|
|
```
|
|
yarn add @docusaurus/core@../../local/docusaurus/node_modules/@docusaurus/core
|
|
yarn add file:../../local/docusaurus/packages/docusaurus
|
|
yarn add link:../../local/docusaurus/packages/docusaurus
|
|
yarn add ../../local/docusaurus/node_modules/@docusaurus/core
|
|
yarn add ../../local/docusaurus/packages/docusaurus
|
|
```
|
|
- You cannot use `npm install` instead of `yarn add` for this purpose.
|
|
- `yarn link` is very likely to fail with react, unless you also manually link react. See https://github.com/facebook/react/issues/14257.
|
|
|
|
## Use Verdaccio
|
|
|
|
Verdaccio is a good local npm server that you can use to test your packages.
|
|
|
|
We have a script `test:build:website` that starts a docker with verdaccio, publishes the packages, and initializes a new website in the parent directory. Alternatively, to install a package in the existing project, after you have started the verdaccio service, run
|
|
|
|
```bash
|
|
npm_config_registry="http://localhost:4873" yarn install @docusaurus/core@"2.0.0-beta.8.NEW" # The version should be the latest
|
|
```
|
|
|
|
You can refer to [the implementation](./scripts/test-release.sh) for more details.
|
|
|
|
If you don't have docker, you can still invoke the CLI manually to start the service.
|
|
|
|
```bash
|
|
npx verdaccio --listen 4873 --config admin/verdaccio.yaml
|
|
```
|