Roam Research Docs · Developer documentation

Roam Depot/Extensions

markdown version · view in Roam Research

Introduction
- 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
  - 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
Developer mode
- Load, test, and iterate on extensions in development — from a local folder, a URL, or a roam-depot PR — without publishing them
- Enable it
  - Visit a graph, open Settings, go to the Roam Depot tab, and click enable developer mode
- Load your extension, from one of three sources
  - A local folder
    - Click "Load extension" and choose the folder on your computer which contains extension.js / extension.css
  - A roam-depot PR, via its "PR-shorthand"
    - Format: username+extension-id+pr-number — e.g. digitalmaster+roam-memo+668
    - The shorthand is posted in an auto-generated comment on the PR at creation/update
    - Loom video walkthrough of loading from a URL / PR-shorthand
      - {{video: https://www.loom.com/share/d6ec8341b17e4959b9604957e7212556}}
  - A URL
    - Pass a URL to the root path where adding the file names to the url leads to your files — README.md and extension.js are required, extension.css and CHANGELOG.md optional. The files have to be publicly accessible
      - Example::
        
        with https://my-extension.pages.dev, the file https://my-extension.pages.dev/extension.js must resolve
      - A common mistake is to forget the https:// prefix
    - Useful for testing on mobile — serve your files on your local network with a tool like https://www.npmjs.com/package/serve
    - Useful for sharing a link with beta testers
      - Developer extensions are local to each client — this is not a replacement for publishing; please only use it for testing
    - To auto-deploy your extension to a URL on every push to main — a persistent link, without opening a PR in roam-depot just to test:
      - Option 1: for a new extension, fork the template repository by Matt Vogel, then go to repo settings > Pages and the Actions tab to set up
      - Option 2: for an existing extension, copy .github/workflows/deploy.yml into your own repository (same path), then go to repo settings > Pages and the Actions tab to set up
      - Short Loom video guiding through both options
        
        {{video: https://www.loom.com/share/4785e95fe5454684a48683402da5ea09}}
      - Longer Loom video through the entire process (relevant if you want to learn how the github action works here)
        
        https://www.loom.com/share/ac50ccf34f924a95bf6be4ca74ab85d7
- Reload after changing your code
  - ctrl-d ctrl-r calls onunload, loads the new code, and calls onload — for all loaded developer extensions
  - You can also reload from Settings > Roam Depot > Developer Extensions
  - If your state isn't properly removed in onunload, reload the page and hit ctrl-d ctrl-r to completely clear the state
- Properties
  - URL / PR extensions are auto-started, similar to production extensions
  - Local-folder extensions are NOT auto-started — load them again from the Roam Depot tab, or with ctrl-d ctrl-r
    - Reading your folder needs file-system permission, which the browser only grants from a user action
  - Developer extensions are NOT synced across devices
  - URL / PR extensions are NOT cached (unlike production Roam Depot extensions) — they are downloaded again every time you open Roam or press reload
Code Guidelines
- Your extension should export as default a map with onload and onunload functions
  - All state setup in onload should be removed in onunload.
  - onload receives an object with the Roam Depot/Extension API in it
  - ```
  export default {
    onload: ({extensionAPI}) => {},
    onunload: () => {}
  };
```
- 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
    - 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
- 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
  - The majority of tailwind css is included with Roam
- 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 import from the window object to make it easier to import global dependencies
      - webpack example
    - 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
        
        react
        
        18.2.0
        
        window.React
        
        react-dom
        
        18.2.0
        
        window.ReactDOM
        
        react-dom/client
        
        18.2.0
        
        window.ReactDOMClient
        
        react-youtube
        
        ^7.13.1
        
        window.ReactYoutube
        
        @blueprintjs/core
        
        ^3.50.4
        
        window.Blueprint.Core
        
        @blueprintjs/select
        
        ^3.18.6
        
        window.Blueprint.Select
        
        @blueprintjs/datetime
        
        ^3.23.14
        
        window.Blueprint.DateTime
        
        chrono-node
        
        ^2.3.2
        
        window.ChronoNode
        
        idb
        
        ^7.1.1
        
        window.idb
        
        nanoid
        
        ^2.0.4
        
        window.Nanoid
        
        file-saver
        
        ^2.0.2
        
        window.FileSaver
        
        crypto-js
        
        ^3.1.9-1
        
        window.CryptoJS
        
        tslib
        
        2.2.0
        
        window.TSLib
    - 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
        
        marked-react
        
        1.1.2
        
        RoamLazy.MarkedReact
        
        marked
        
        4.3.0
        
        RoamLazy.Marked
        
        jszip
        
        ^3.10.0
        
        RoamLazy.JSZip
        
        cytoscape
        
        ^3.7.2
        
        RoamLazy.Cytoscape
        
        insect.js
        
        5.6.0
        
        RoamLazy.Insect
- 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
Submitting an extension
- 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)
  - If your extension bundles dependencies and requires a build step
    - Provide a build.sh file
    - The build.sh file will be invoked before looking for extension.js (required) or extension.css (optional)
    - The environment it’ll be invoked in is ubuntu-24.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.
  - If not and your extension is a simple javascript file, then you can write all of your code in extension.js (required)
- 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
    }
```
- Fields
  - name (string, required) — your extension's display name in Roam Depot
  - short_description (string, required) — one-line description shown in the extension list
  - author (string, required) — the author name shown to users
  - tags (array of strings, optional) — keywords for finding your extension
  - source_url (string, required) — link to your extension's repo, shown to users
  - source_repo (string, required) — the git URL your code is fetched from (ends in .git)
  - source_commit (string, required) — the exact commit that gets reviewed, built, and published — bump this to release an update
  - stripe_account (string, optional) — your Stripe account ID; only include it if you want payouts from Roam
- Then make a Pull Request with this change. After it’s merged, your extension will be published in the Roam Marketplace.
Updating an extension
- Every update to your extension will be reviewed, submitting it is the same as Submitting an extension
- Just update the source_commit in your extension's metadata file in your fork of https://github.com/Roam-Research/roam-depot
  - You may also change other values of your metadata file
Tutorials
- 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
Examples
- 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