NotePlan Plugins provides an extensive API for extending default editing and task management and work across all platforms (macOS and iOS).
Each plugin command can be invoked using the NotePlan Command Bar, or by entering any of available commands directly in the editor by entering /<command_name> (NotePlan will auto update the list of possible commands as you type)
If you want to develop plugins, Step 1 is to read the NotePlan Knowledgebase Document describing how plugins work in NotePlan and the basic plugin anatomy. Once you have read that carefully and understand the basics, you should return here to acquire and start using the NotePlan Plugin tooling described below.
The following items are required for NotePlan Plugin Development
- Node 14 or 16 -- Do Not Use any Node version <14 or >16 (see "Switching Node Versions")
- NotePlan 3.4 or greater
- macOS Catalina 10.15.2 or greater (strongly recommend macOS Big Sur 11.x or Monterey 12.x)
- github CLI
ghis strongly recommended - how to install gh
The NotePlan plugin code has not yet been migrated to Node versions >16. If you are developing elsewhere using Node v17+, you will want to switch to Node v16 when you are doing NotePlan Plugin development. The fast/easy way to do that is with a Node version manager like "n". This way you can flip in and out of Node versions at will.
If you have an idea for a plugin, submit them here or inquire in the NotePlan Discord community's #plugin channel.
If you are a developer and want to contribute and build your plugins, see the plugin writing documentation and discuss this with other developers on Discord #plugin-dev channel. You might want to consult this good modern JavaScript tutorial.
Step 1: Forking/Cloning NotePlan Plugin Repository
Read these instructions for how to fork and clone this code
Step 1.5 Have a look at the code
When you have cloned this repository, you will not only have the tooling, but you will have the actual source code for every publicly-available NotePlan plugin. This will give you a wealth of material to learn from and borrow from. Speaking of which, there is a /helpers directory at the root of the repository that contains a lot of useful functions built upon the NotePlan APIs and will speed up your development. It would be good to familiarize yourself with that code by browsing it. There is a searchable index of the helper code that can be accessed by running this command in a terminal:
npm run docs
Step 2: Install Node (if not installed)
Make sure you have the proper version of node installed (if you need to install node, brew install node@16 is the quickest method, or you can follow instructions on node website).
Step 3: Initialize Local Development Environment
Run the following 3 commands from the root of your local GitHub repository for NotePlan/plugins.
- Update node-gyp
npm i -g node-gyp@latest && npm config set node_gyp "/usr/local/lib/node_modules/node-gyp/bin/node-gyp.js"Note: Don't be surprised if this command fails. It is only necessary in certain cases. If it fails, it probably means you didn't need it. Just continue on.
- Install the node_modules
npm installNOTE: if you are running node >= 16 and you get failure messages on the vanilla install command above, you will need to use this command instead:
npm install --legacy-peer-deps
- Link the files to make them run properly from the command line (especially the
noteplan-cli)
npm run initThis will install the necessary npm dependencies and initialize your plugin working directory, including:
- Configuring
eslinteslint (for checking code conventions) - Configuring
flowflow (for type checking) - Configuring
babelbabel (a JS compiler) - Configuring
rolluprollup (for bundling multiple source files into a single release).
Each of these tools have their own configuration files at the root directory (e.g., .flowconfig or .eslintrc)
Note: Each of these configuration files can be overridden if needed by placing a project specific configuration file in you project plugin, however, for consistency with other NotePlan plugins, we encourage to use the defaults wherever possible.
Using the NotePlan CLI, perform the following actions:
Step 1: Create your plugin using NotePlan CLI
Answer the prompt questions (or supply all the necessary options from command line (see noteplan-cli plugin:create --help for details)
noteplan-cli plugin:create
Step 2: Startup Auto Watch Process
Open up a Terminal shell, cd to the repository root directory, and issue the command:
npc plugin:dev <your_plugin_folder> --watch from the root directory to build your plugin as you develop so it can be tested in NotePlan. This will compile your code and put it into your NotePlan app directory so you can test your plugin. The --watch flag keeps the process looking for changes to your files and will automatically rebuild the plugin for you. (more on that below)
Step 3: Start your plugin command develop and test locally
You can now develop and test your plugin locally,
Step 4: Create Pull Request (if you wish to make your plugin public)
At this point, if you would like to make your plugin available publicly, you can proceed to creating a Pull Request to have your code included in the NotePlan Plugin Repository
These are the most common commands you will use while developing:
The default watch command npc plugin:dev <your_plugin_folder> --watch:
npc plugin:dev from the root of your local NotePlan/plugins repository which will bundle all the files in your /src directory into single file script.js and will be copied from your repository directory to your Plugins folder in the running NotePlan data directory for testing.
The init script should have detected whether you are using the SetApp or App Store version of NotePlan and set the correct path to your Plugins folder. If it did not, you can manually change it in .pluginpath.
Note: The watcher will remain running, watching the NotePlan directory and re-compile whenever changes have been made to your <your_plugin>/src JavaScript files.
npc plugin:dev <your_plugin_directory> --watch
For example, running npc plugin:dev dwertheimer.TaskAutomations --watch will perform the same watching operations for the dwertheimer.TaskAutomations plugin only.
NotePlan includes a suite of CLI commands which you can use during development.
noteplan-cli <command>
or
npc <command>For all CLI commands, you can pass the --help for available flags
The most common CLI command, this can be used to build plugin, test plugins (wrapper for npc plugin:test)
npc plugin:dev <plugin> [options]
# run watcher, compact mode and display notification with build result
npc plugin:dev codedungeon.Toolbox --watch --compact --notify
# same as above, using CLI shorthand
npc plugin:dev codedungeon.Toolbox -wcn
# run NotePlan test suite in watch mode
# this is a wrapper for npc plugin:test
npc plugin:dev codedungeon.Toolbox -tw
The test command can be used in addition to the npc plugin:dev <plugin> --test which will only execute the NotePlan Test Runner
npc plugin:test <plugin> [options]
# execute test running in watch mode, with silent enabled
npc plugin:test codedungeon.Toolbox --watch --silent
# as with other plugin commands, youc an use CLI shorthand
# this will perform the same as above
npc plugin:test codedungeon.Toolbox -wsCreate new NotePlan Plugin
npc plugin:create [options]Create NotePlan Plugin Pull Request
npc plugin:pr [options]Run test suite for NotePlan Plugin
npc plugin:test <plugin> [options]
# run plugin:test watch
npc plugin:test codedungeon.Toolbox --watch
# run plugin:test watch, silent mode
npc plugin:test codedungeon.Toolbox --watch --silent
# run plugin:test with CLI shorthand
npc plugin:test codedungeon.Toolbox -ws
# run plugin:test with coverage report
npc plugin:test codedungeon.Toolbox --coverageOnce you are finished editing and testing your plugin, you can submit a Pull Request to the NotePlan/plugins repository and it will be reviewed for inclusion. Once it has been approved, it will be available from NotePlan > Preferences > Plugins section, enabling it to be installed by other NotePlan users.
The common script you will run npc plugin:dev <plugin> however, you may need to use any of the following
npc plugin:dev <plugin> --watch --compact --notifya less verbose version ofautowatchthat might suit more experienced developersnpc plugin:dev <plugin> -wcnwatcher, compact mode, notify using CLI shorthandnpc plugin:dev <plugin> -twtest mode, watcher using CLI shorthandnpc plugin:test <plugin> -wtest mode, usingtestcommandnpm run typecheck: typecheck all javascript files withFlow. Only files with a// @flowcomment are checked.npm run fix: lint and auto-formatnpm run docs: build documentation for javascript filesnpm run lint: run ESlint on the entire reponpm run lint-fix: run ESlint on the entire repo and fix whatever it can automatically fixnpm run format: auto-format all Javascript files usingprettiergh release delete <release name>: Will delete the release from the repository, so making it unavailable in NotePlan as well. (Though it won't remove it from anyone who has already downloaded it.)
Use the setup guide for your preferred editor (we prefer Visual Studio Code), and then read the section on Working with Multiple Files.
Install VSCode Extensions
- Install the following extensions for the following tools:
flow"Flow Language Support" by flowtypeeslint"ESLint" by Dirk Baeumerprettier"Prettier - Code formatter" by Prettier- (optional) "TODO Highlight V2" by wayou/jgclark
Update Settings
- Set
prettierto be the default formatter for js files.- You can open the Command Bar using
CMD+SHIFT+Pand then search forFormat Document. - When you do this, you may get asked for a formatter of choice. Choose "Prettier"
- If it asks you if this should be your default for all JS files, choose Yes.
- You can open the Command Bar using
- Restart the editor to ensure the plugins are working.
- You should see type errors when you make those
- You should see lint errors when you format code wrong
- You should see your code get auto formatted when you save
- Make sure to open this folder directly in VSCode and not the entire repo as the ESLint plugin can be annoying about that
- Install the following extensions using Package Control
SublimeLinterThis allows various linters to workSublimeLinter-eslintSublimeLinter-flowjsPrettierBabelSyntax definitions for ES6 Javascript and React JSX extensions
- Configure your packages:
- Open a
.jsfile - From the View menu, select Syntax → Open all with current extension as… → Babel → JavaScript (Babel)
- Open the package settings for
jsPrettierand add"auto_format_on_save": true,
- Open a
If you don't have an editor set up to lint as you code, you can run npm run test and it will give a list of problems to fix.
By practice, NotePlan plugins use flow for static type checking. You can get more information by referencing NotePlan Flow Guide
Should you need support for anything related to NotePlan Plugins, you can reach us at the following:
If you would prefer email, you can reach us at:
Perhaps the fastest method would be at our Discord channel, where you will have access to the widest amount of resources:
This is a great resource to request assistance, either in the form of a bug report, or feature request for a current or future NotePlan Plugin
If you would like to contribute to the NotePlan Plugin repository, feel free to submit a Pull Request for any existing NotePlan Plugin, or any of the support materials.