NotePlan Plugins

This is the initial repository for NotePlan app plugins, available from release v3.0.22 (Mac & iOS).

The plugins work through Command Bar Plugins for example:

If you are a user and have plugin ideas, submit them here or ask in the NotePlan Discord community's #plugin-ideas 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. Your might want to consult this good modern JavaScript tutorial.

More instructions below:

Set up Repo and Tools

Clone this repository
Make sure you have a recent version of node and npm installed. brew install node should do the trick.
Run npm install from the root of your local GitHub repository for noteplan/plugins. This will install all the dependencies. This includes setting up eslint (for checking code conventions), flow (for type checking), babel (a JS compiler), and rollup (for bundling multiple source files into a single release). Each have their own configuration files in the root; they can be overridden if needed by placing a more specific config file in the respective plugin's folders.
Run npm run autowatch from a terminal in the GitHub root folder. The first time you run the script it will ask you for the full path to your live Plugins folder, and if you provide it, it will automatically copy the final js file and the plugin.json file in there automatically.

Install GitHub command line tools gh and authorise it for future use:

> brew install gh
> gh auth login
Github.com > HTTPS > Yes Credentials > Login with web browser
Enter (copy OTP code from command line)
[Paste OTP code in browser window]

If you want to create a new plugin, an easy way is to copy the np.plugin-flow-skeleton folder and rename it per the instructions in the readme (here's where you'll create your plugin)
Now get your IDE set up per the instructions below (Editor Setup)

Developer Automation Commands

These are the most common commands you will use while developing:

npm run autowatch from the root of your local GitHub NotePlan/plugins repo and your multi-file JS plugins will be compiled for you and copied from your repository directory to your Plugins folder in the running NotePlan data directory for testing. Not only that but it will then continue to watch the folder and re-compile every time you save changes to a Javascript file. NB: by default, autowatch (without any other arguments) command will rebuild all plugins just in case shared files affect another plugin. If you want to focus autowatch on a subset of plugins, you can pass the plugin folder name to autowatch like so:

npm run autowatch dwertheimer.TaskAutomations

Note: by default, for compatibility with older Macs, the plugins are transpiled into ES5 Javascript before they are copied to the Plugins folder. This works great, but if you want to try to debug in the Javascript debugger, the transpiled code won't match your code. So for Javascript debugging purposes, use this command instead:

npm run autowatch dwertheimer.TaskAutomations -- --debug

That will bundle your code together into one script.js file but will not transpile it to ES5.

Then, when you are done debugging, build the plugin properly for release using the non-debug version above.

Note: if you wish to have a more compact output, without listing the debug and release commands to use each time, then append the -- --compact flag.

If you have write permissions on the repository and want to release the plugin for all Noteplan users to see, run npm run release "<plugin folder name>" (e.g. npm run release "jgclark.DailyJournal") which will do all the work necessary to create/update a release in GitHub for the plugin. This will then automatically be available to all NotePlan users from the Plugins preference pane.

Note: The autowatch command is typically the only one you will need to use, especially if you use an IDE (e.g. VSCode) that does typechecking.

However, the following ones may be needed at times:

npm run build: Will build all the plugins into single files (where needed)
npm run watch: Will watch all files for changes and automatically compile them into single javascript files (where needed)
npm run typecheck: Will typecheck all the javascript files with Flow. Only files with a // @flow comment are checked.
npm run fix: Will lint and autoformat
npm run test: Will lint and typecheck all Javascript files and report, but not fix anything
npm run lint: Will run ESlint on the entire repo
npm run lint-fix: Will run ESlint on the entire repo and fix whatever it can automatically fix
npm run format: Will autoformat all Javascript files.
gh 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.)

Editor Setup

Use the setup guide for your preferred editor (we prefer Visual Studio Code), and then read the section on Working with Multiple Files.

Visual Studio Code (recommended)

Install extensions for the following tools:
1. flow "Flow Language Support" by flowtype
2. eslint "ESLint" by Dirk Baeumer
3. prettier "Prettier - Code formatter" by Prettier
Update Settings:
Set prettier to be the default formatter for js files.
- You can open the Command Bar using CMD+SHIFT+P and then search for Format 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.
Restart the editor to ensure the plug-ins 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 autoformatted when you save
Make sure to open this folder directly in VSCode and not the entire repo as the ESLint plug-in can be annoying about that

Sublime Text 3 and 4

Install the following extensions using Package Control
1. SublimeLinter This allows various linters to work
2. SublimeLinter-eslint
3. SublimeLinter-flow
4. jsPrettier
5. Babel Syntax definitions for ES6 Javascript and React JSX extensions
Configure your packages:
1. Open a .js file
2. From the View menu, select Syntax → Open all with current extension as… → Babel → JavaScript (Babel)
3. Open the package settings for jsPrettier and add "auto_format_on_save": true,

Working with multiple files

Noteplan plugins need to be packaged as a single Javascript file, but that's not always a nice way to work. So we use tools to package up multiple files into one.

Open up a terminal, and run npm run autowatch which will keep watching for JS file changes and will package up the plugin and copy it to your app Plugins directory.

If you don't have an editor set up to lint on the fly for you, run npm run test and it will give a list of problems to fix.

Read the basic of how to use Flow type checking in the Flow Guide

Contributing

The easiest way to contribute is to make addtions/changes using Gitub and issue a Pull Request on the Noteplan github.

scholzie / plugins