If you would like to contribute to the development of dendron, you can do so by checkout out the repo from github.
You can then follow the setup instructions below to prepare your first commit!
Before you begin, you need to make sure to have the following SDKs and tools:
- Node.js >= 12.0.0
- We recommend using a version in Active LTS
npm install -g yarn
npm install -g lerna
- a different instance of VSCode
- because debugging VSCode by default loads up all extensions that are installed, you'll have issues trying to develop Dendron if you also have VSCode installed . the workaround is to install an alternative flavor of vscode (eg. insider edition) to use for development
git clone https://github.com/dendronhq/dendron.git cd dendron
# this should install all dependencies yarn setup # if the above script errors out, you can diagnose the issue and run the following scripts sequentially dependeing on where the error occured yarn # install package root dependencies yarn bootstrap:bootstrap # install package dependencise yarn bootstrap:build # build package dependencies
- Open the workspace. At the root of the monorepo, open
dendron-main.code-workspace. Open this with VSCode to start editing. While its not required to use VSCode, most of the helper scripts in this repository are created with VSCode in mind so using it will make development significantly easier.
- NOTE: you don't need to do this if you are not directly working on the extension (eg. you're working on the server)
To start an instance of the Dendron with the Debugger, Run
Extension: Local (plugin-core) from the debug panel in vscode
Note: Running via Run -> Start Debugging will not work unless you've previously targeted
Extension: Local (plugin-core)
Note: To have the changes reflected as you edit the code you need to run the
./bootstrap/scripts/watch.sh and restart the
Extension: Local (plugin-core))
If you are developing Dendron in a remote environment using VSCode, see additional instructions here.
- Checkout a feature branch for your task
- Work on code
- Submit a pull Request
Logs are important for debugging and we should strive to have logs that will give enough information that we can debug any errors from the logs alone. Because we're dealing with users personal notes, we also need to ensure not to log any sensitive information.
If you need to log data, use one of the following loggers depending on what package you are in:
- plugin-core: use Logger
- react component: use createLogger in common-frontend
- everything else: use createLogger in common-server
Also note that many objects (eg. commands, pods, etc), have an instance of the logger attached to them. You should use them whenever available. They are usually attached as a
- pods have loggers attached in
Some things to keep in mind:
- Do not use
console.logto log data
- Raw note objects contain note content which we never want to log. Instead, use
NoteUtils.toLogObjwhich strips out sensitive fields to the logger.
When handling a Dendron specific error, use the DendronError class
Some things to keep in mind:
- when returning an error from the server, note that you'll need to convert the error to a plain object using error2PlainObject
- when displaying an error in a string, you'll need to convert the error using stringifyError
- whenever possible, attach a status to an error
- whenever possible, attach a severity to an error
Project Specific Docs
Working with the API Server
Dendron connects to a local express server which is responsible for indexing your notes. This express server also serves up static files generated by Dendron Next Server.
Dendron compiles the static assets from the next server to the express server during publication so that everything is bundled when published. When you are developing, you can launch the next server independently for faster development. You can follow the instructions here to start the next-server.
To start Dendron with the next server active, you can set the following value in
dev: nextServerUrl: "http://localhost:3000"
Working with the CLI
cd packages/dendorn-cli npm link npm link -g @dendronhq/dendron-cli
Verdaccio is an open source local NPM registry. We use it to test out publishing and link together projects internally before publishing
- NOTE: only run verdaccio when you need to test publishing. otherwise, this will pollute the
localhostentries which will fail in CI/CD
Linking all Packages
This goes over symlinking all packages locally. This requires that the
meta.json file be generated. It is created as part of
To continuously compile all dependencies, run the following
When you are merging new changes, note that new dependencies and sometimes packages will be installed.
# install all new dependencies lerna bootstrap
New Package in Dendron Mono Repo
Adding new packages is a rarer event but might require a workspace rebuild
# clean up old files (this might take a few minutes) ./bootstrap/scripts/cleanup.sh # install all dependencies lerna bootstrap # build all dependencies ./bootstrap/scripts/build.sh
Something went wrong during the build
In case something something goes wrong with a build step or you want to save time by not running everything,
init.sh is just a thin wrapper around the following scripts, each of which can be run individually
lerna bootstrap all packages
lerna build all packages
Changes not showing up in Dendron
Are you using the
Run extensioncommand on the debugger panel to test dendron?
If you have one vscode instance which you have dendron installed and are also doing dendron development on, you might get a version conflict. in that case, use
Run extension with plugin disabledin the debugger panel (or use a different version of vscode to run dendron vs develop)
Husky Hooks not running
Make sure you run
yarn at the root of your workspace
Dendron is actively being developed and it could be quite confusing to start developing for the first time. In this case, we recommend asking for help with whatever blockers you might have with setting up or understanding part of the codebase.
Generally, a member of the Dendron team or the community will chime in for help if you post a specific question in the
#dev channel in our Discord server.
For more information, check out our handbook entry on
Getting help for development described here