Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Admin: Using a local Docusaurus package for testing (#110)
This is good if you want to test your latest code changes without publishing to the real npm server. Two ways: 1. install package from the Docusaurus repo itself (note the clowntown I had to run into - we can talk about this @hramos) 2. Use verdaccio (or other local npm server)
- Loading branch information
1 parent
14dfcff
commit a73438f
Showing
1 changed file
with
125 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,125 @@ | ||
Sometimes you want to test the latest version of Docusaurus via `npm` or `yarn` without having to publish it to npm itself. For example, you may want to use the latest code in `master`. | ||
|
||
There are a couple of ways to use a local version of an npm package. | ||
|
||
## Install from a local Docusaurus repo | ||
|
||
> If you want to use the docusaurus-init script for testing, you will have to update the `initialize.js` file to point to the local Docusaurus repo instead of installing it from the npm server. In some ways, it is just easier to do the manual steps. | ||
### Install the package from the Docusaurus repo | ||
|
||
``` | ||
cd /path/to/testing_project | ||
mkdir website # if this does not exist already | ||
cd website | ||
``` | ||
|
||
If you do not have a `package.json` file in the `website` directory, create one with the following content: | ||
|
||
``` | ||
{ | ||
"scripts": { | ||
"start": "docusaurus-start", | ||
"build": "docusaurus-build", | ||
"publish-gh-pages": "docusaurus-publish", | ||
"examples": "docusaurus-examples" | ||
} | ||
} | ||
``` | ||
|
||
Then: | ||
|
||
``` | ||
# Path to your Docusaurus clone | ||
npm install ../../path/to/docusaurus/ | ||
``` | ||
|
||
### Clowntown! | ||
|
||
Now, we have a bit of clowntown here in the way symlinks are handled. The above `npm install`, creates a `node_modules` directory with a symlink in it. And errors will result if you try to access the local site after starting the server (as you do below). You will get something like this error: | ||
|
||
``` | ||
Error: Couldn't find preset "react" relative to directory | ||
``` | ||
|
||
So, you should install these packages locally. **Base the versions on the versions defined in the Docusaurus `package.json`**. e.g., | ||
|
||
``` | ||
# Still in the website directory of the testing project | ||
npm install babel-preset-react@^6.24.0 | ||
npm install babel-preset-env@^1.6.0 | ||
npm install react@^15.5.4 | ||
``` | ||
|
||
### Test | ||
|
||
``` | ||
./node_modules/.bin/docusaurus-examples # or whatever you want to test, if anything | ||
./node_modules/.bin/docusaurus-start | ||
``` | ||
|
||
## Use Verdaccio | ||
|
||
Verdaccio is a good local npm server that you can use to test your packages. | ||
|
||
### Install verdaccio | ||
|
||
``` | ||
npm install --global verdaccio | ||
``` | ||
|
||
### Publish to verdaccio | ||
|
||
When you are ready to test the code that could make up the next version of your package, you can publish locally to verdaccio | ||
|
||
Run verdaccio in a **separate terminal window**: | ||
|
||
``` | ||
verdaccio | ||
``` | ||
|
||
In another terminal window, get ready to publish your local npm package: | ||
|
||
``` | ||
# Your clone of Docusaurus | ||
cd /path/to/docusaurus/ | ||
# use anything for user, password, email | ||
# You should only have to do this once as long as you keep verdaccio installed | ||
npm adduser --registry http://localhost:4873 | ||
npm publish --registry http://localhost:4873 | ||
``` | ||
|
||
You can navigate to localhost:4873 and you can see that your package was published. You can also see it showing you the steps you ran above as well. | ||
|
||
### Install the local npm package and test | ||
|
||
Now install the package in the repo you want to test Docusaurus on. | ||
|
||
``` | ||
cd /path/to/testing_project/ | ||
mkdir website # if this does not exist already | ||
cd website | ||
``` | ||
|
||
If you do not have a `package.json` file in the `website` directory, create one with the following content: | ||
|
||
``` | ||
{ | ||
"scripts": { | ||
"start": "docusaurus-start", | ||
"build": "docusaurus-build", | ||
"publish-gh-pages": "docusaurus-publish", | ||
"examples": "docusaurus-examples" | ||
} | ||
} | ||
``` | ||
|
||
Then: | ||
|
||
``` | ||
npm install docusaurus --registry http://localhost:4873 # this may be slower than the normal npm registry | ||
npm run examples # or whatever you want to test, if anything | ||
npm run start | ||
``` |