Skip to main content
Documentation Configuration Plugins

Gem-based Plugins and the Frontend

When authoring a plugin or theme for Bridgetown, you may find yourself wanting to ensure users of your plugin are able to load in your frontend assets through esbuild (such as JavaScript, CSS, etc.) The best way to do this is to set up a package.json manifest and publish your frontend code as a package to the NPM registry.

Let’s assume you’ve been building an awesome plugin called, unsurprisingly, MyAwesomePlugin. In your my-awesome-plugin.gemspec file, all you need to do is add the npm-add metadata matching the NPM package name and keeping the version the same as the Gem version:

  spec.metadata = { "npm-add" => "my-awesome-plugin@#{MyAwesomePlugin::VERSION}" }

With that bit of metadata, Bridgetown will know always to look for that package in the users’ package.json file when they load Bridgetown, and it will trigger a npm install command (or equivalent for Yarn or pnpm) if the package and exact version number isn’t present.

The SamplePlugin demo repo includes a script/release command you can use to run the test suite, release a new version of the gem, and release a new version of the NPM package all in one go. (This will also be present if you set up your plugin using the bridgetown plugins new command.)

Make sure you update package.json!

If you bump up your Ruby version number and forget to bump the NPM package version at the same time, the packages will get out of sync! So remember always to update version.rb and package.json so they have the same version number.

You will need to instruct your users how to add the plugin’s frontend code to their esbuild entry points. For example, they might need to update frontend/javascript/index.js with:

import MyAwesomePlugin from "my-awesome-plugin"

const awesomeness = new MyAwesomePlugin()
awesomeness.doCoolStuff()

Consider writing an automation to make this process easier for users.

Back to Plugins