- Your extension's code runs alongside Roam's code, the same as roam/js, with full access to the dom and the Roam Alpha API, and a new Roam Depot/Extension API
- Every update to your extension will be submitted and reviewed for security by Roam's team through the github repo
- In an effort to support authors and encourage ongoing maintenance of extensions, Roam is dedicating a portion of our revenue to extension authors.
- The amount and way we distribute funds is subject to change
- If you are interested in receiving payouts, sign up with stripe in extension settings and add your account ID to your extension's metadata
- Please complete the process in full and make sure your account is enabled submitting an extension with the account attached. We can only send funds if your account is fully filled out. You can contact Josh on slack if you do not know if your account is enabled or not.
- We should be able to support authors in all of the countries listed in https://stripe.com/docs/connect/cross-border-payouts (not the preview ones yet, but if you are in one of those contact us first and we can try to get it working).
- Legally, if you make more than $600 per year from Roam and live in the US, you are expected to pay taxes on it and can ask Roam for a 1099 form
- Please complete the process in full and make sure your account is enabled submitting an extension with the account attached. We can only send funds if your account is fully filled out. You can contact Josh on slack if you do not know if your account is enabled or not.
- Paid extensions do not exist yet, but in the future we hope to add them. You may implement your own payment system for an extension, but this will disqualify you from payouts from Roam
- Your extension should export as default a map with
onloadandonunloadfunctions- All state setup in
onloadshould be removed inonunload. onloadreceives an object with the Roam Depot/Extension API in itexport default { onload: ({extensionAPI}) => {}, onunload: () => {} };
- All state setup in
- Roam APIs
- You'll have access to two different APIs for development, the Roam Alpha API and the Roam Depot/Extension API
- Why two?
- The Roam Alpha API was developed before the existence of Roam Depot, and modifying that to fit the needs of Roam Depot would break existing roam/js extensions
- Particularly, for Roam Depot, we can pre-fill functions with information about your extension and automatically remove components when your extension is uninstalled
- Eventually, everything will be duplicated inside of the Roam Depot/Extension API for ease of use
- The Roam Alpha API was developed before the existence of Roam Depot, and modifying that to fit the needs of Roam Depot would break existing roam/js extensions
- Please read the documentation for these, there is likely already a method for what you need and if there isn't let us know in the #developers channel on slack
- Why two?
- You'll have access to two different APIs for development, the Roam Alpha API and the Roam Depot/Extension API
- User Interface
- Extensions should prefer using blueprintjs components to match Roam's style
- Styles
- Extensions should prefix css classes with a unique identifier such that it won't conflict with roam or other extensions.
- Example::
- Roam uses
rm-in front of all our css classes,rm-modal
- Roam uses
- Example::
- The majority of tailwind css is included with Roam
- Extensions should prefix css classes with a unique identifier such that it won't conflict with roam or other extensions.
- Dependencies
- Your dependencies will be scrutinized heavily, some general guidelines
- If you can do it without a dependency, do not use a dependency
- Only use trustworthy dependencies, extensions will be rejected if our team decides one of your dependencies is untrustworthy
- Roam exports a number of dependencies for extensions to use. Extensions must use these instead of bundling their own version or a library similar to one of these.
- Your bundler may support
importfrom the window object to make it easier to import global dependencies - Alternatively, you access them from the window object
- Sync dependencies
- Dependencies bundled with Roam core will be provided on the window object
- {{table}}
- Package Name
- Version
- Global Var
- Version
react18.2.0window.React
react-dom18.2.0window.ReactDOM
@blueprintjs/core^3.50.4window.Blueprint.Core
@blueprintjs/select^3.18.6window.Blueprint.Select
@blueprintjs/datetime^3.23.14window.Blueprint.DateTime
chrono-node^2.3.2window.ChronoNode
idb7.1.1window.idb
nanoid^2.0.4window.Nanoid
file-saver^2.0.2window.FileSaver
crypto-js^3.1.9-1window.CryptoJS
tslib2.2.0TSLib
- Package Name
- Async dependencies
- Some of Roam's dependencies are loaded only when a user uses them, your extension should do the same thing
- We understand dynamically loading is pretty difficult for a beginner, if that is you, you can ask us for help or for an exception to this rule
- {{table}}
- Package Name
- Version
- Global Var
- Version
marked-react^1.1.2RoamLazy.MarkedReact
marked4.3.0RoamLazy.Marked
jszip^3.10.0RoamLazy.JSZip
cytoscape^3.7.2RoamLazy.Cytoscape
insect.js5.6.0RoamLazy.Insect
- Package Name
- Some of Roam's dependencies are loaded only when a user uses them, your extension should do the same thing
- Your bundler may support
- Your dependencies will be scrutinized heavily, some general guidelines
- Offline
- Extensions will run offline, your extension doesn't have to work offline but it should be aware it could be running without network connection and handle that accordingly
- Allowed languages
- Typescript, Javascript, or Clojurescript
- To develop locally, you'll have to use this url https://relemma-git-roam-app-store.roamresearch.com (until we launch)
- Visit a graph, open up settings, and go to the extensions tab
- Then click enable developer mode
- Then load extension
- and choose the folder on your computer which contains
extension.js/extension.css - To reload the extension you can use the key command
control-d control-r, which will call your extension'sunloadfunction, load the new code, and callonload- Note that this key command reloads all loaded developer extensions
- You can also reload extensions from the extensions tab in settings
- Note that this key command reloads all loaded developer extensions
- If your state isn't properly removed in
unloadthen you can reload the page and hitcontrol-d control-rto completely clear the state
- Create a github repo for your extension
- Inside your repository
- Provide
- README.md (required)
- This will be displayed to users inside of Roam, include any relevant long description for your extension
- extension.js (required)
- extension.css (optional)
- CHANGELOG.md (optional)
- README.md (required)
- If your extension bundles dependencies and requires a build step
- Provide a
build.shfile - The
build.shfile will be invoked before looking for extension.js (required) or extension.css (optional) - The environment it’ll be invoked in is ubuntu-20.04 from Github Actions. Consult this to see what is available. (npm and yarn are available)
- If your build script requires anything extra (e.g. libraries from NPM), it should download them as a part of build.sh execution.
- Provide a
- If not and your extension is a simple javascript file, then you can write all of your code in extension.js (required)
- Provide
- Fork https://github.com/Roam-Research/roam-depot
- Create metadata file in extensions/<your username>/<your repo>.json
- Example
extensions/tonsky/roam-calculator.json- with the following content
{ "name": "Test Extension 1", "short_description": "Prints 'Test message 1'", "author": "Nikita Prokopov", "tags": ["print", "test"], //optional "source_url": "https://github.com/tonsky/roam-calculator", "source_repo": "https://github.com/tonsky/roam-calculator.git", "source_commit": "d5ecd16363975b2e7a097d46e5f411c95e16682d", "stripe_account": "acct_1LGASrQVCl6NYjck" // optional only include if you want to be eligible for payouts from Roam }
- Then make a Pull Request with this change. After it’s merged, your extension will be published in the Roam Marketplace.
- Every update to your extension will be reviewed, submitting it is the same as Submitting an extension
- Just update your extension's metadata file in your fork of https://github.com/Roam-Research/roam-depot with a new commit hash
- You may also change other values of your metadata file
- Motivation::
- Make it easier to test extensions
- using this, can easily test on mobile. Can also give links for testers / beta users to test
- Make it easier to test extensions
- Two accepted formats
- "PR-shorthand" format
- You can get the PR-shorthand for your PR from a comment which is auto-generated on the PR at creation/update.
- For example:
digitalmaster+roam-memo+668is the PR-shorthand for PR 668, and is mentioned in this github comment on the PR: https://github.com/Roam-Research/roam-depot/pull/668#issuecomment-1524315888 - ---
username + “+” + extension-id + “+” + pr-number
- URL
- URL to root path where adding
README.mdandextension.jsto the url leads to the required files - Example:
https://roam-excalidraw-depot.pages.dev/- just a test extension I was working on before upgrading native excalidraw. So, I would recommend not using this version of excalidraw. Use
/excalidrawinstead
- just a test extension I was working on before upgrading native excalidraw. So, I would recommend not using this version of excalidraw. Use
- Things to keep in mind:
- the extension files have to be publicly accessible when the file names (i.e. "extension.js", "README.md", "extension.css", "CHANGELOG.md") are added to the end of the passed URL. (only the first 2 are compulsory)
- One common mistake is to forget the prefix in URLs like
https://
- We expect URLs will be useful if you want to
- During development, test extension on mobile
- using a local server like https://www.npmjs.com/package/serve to serve your files on your local network
- note that to load the changed files, you either have to reload Roam or go to Settings>Roam Depot>Developer Extensions and click on reload button
- Have a URL with the latest update of your extension
- (you could then share it with beta-testers)
- An important point is that since developer extensions are local to the client, this is not a replacement for actual "production" extensions. Please only use it for testing
- a guide which might come in handy:
- A guide for how to deploy extension automatically when pushed to
mainbranch in your github repo (in case you want a persistent link or don't want to have to create a PR in roam-depot before further testing)- Option 1: If you're creating a new extension, just fork this template repository by Matt Vogel https://github.com/8bitgentleman/roam-depot-extension-template and then go to repo settings > Pages and then the Actions tab in order to setup
- Option 2: If you already have an extension, you can copy the .github/workflows/deploy.yml file to your own github repository (make sure to have the same path) and then go to repo settings > Pages and then the Actions tab in order to setup
- Short Loom video guiding through both of the above options
- {{video: https://www.loom.com/share/4785e95fe5454684a48683402da5ea09}}
- ---
- Loom video guiding through entire process (might only be relevant if you want to learn how github actions works in this case)
- https://www.loom.com/share/ac50ccf34f924a95bf6be4ca74ab85d7
- Loom video guiding through entire process (might only be relevant if you want to learn how github actions works in this case)
- A guide for how to deploy extension automatically when pushed to
- (you could then share it with beta-testers)
- During development, test extension on mobile
- URL to root path where adding
- "PR-shorthand" format
- Properties
- Remote Dev Extensions are auto started similar to production extensions
- Remote Dev Extensions are NOT cached (unlike production Roam Depot extensions). They are downloaded again every time you open Roam or press refresh
- Remote Dev Extensions are NOT synced across different devices
- Loom video
- {{video: https://www.loom.com/share/d6ec8341b17e4959b9604957e7212556}}
- Simple walkthrough of porting a roam/js extension to Roam Depot, without any git knowledge
- {{video: https://www.loom.com/share/4027806b92d54e539db272ebf7efffec}}
- More complicated example of porting Auto Tag roam/js to Roam Depot
- Sorry this one is pretty long!
- In the video we
- Set up npm and webpack
- port inlined libraries to npm requires
- port settings from being changed in a code block to the new settings panel
- {{video: https://www.loom.com/share/d54eea88013c4d0e8d55cc6dc49e9479}}
- Video got cut off at the end, but only things left were to finish NLP dates and submit
- Submission you can see in Simple walkthrough of porting a roam/js extension to Roam Depot, without any git knowledge
- repository https://github.com/panterarocks49/autotag
- Video got cut off at the end, but only things left were to finish NLP dates and submit
- Bitcoin Price Tracker
- Simple example, with no build process
- Auto Tag
- Simple example, with a build process
- Roamjs Query Builder
- Complicated example, with a complex build process