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.