@ophidian/build
v1.2.1
Published
A build/publish system for Obsidian Plugins
Downloads
22
Readme
@ophidian/build: A Build & Publish System for Obsidian Plugins
This module provides a complete build system for Obsidian plugins including a Github action for publishing them, without needing to duplicate large amounts of code and configuration between plugins. (The build and publish parts are actually independent: you don't have to use the builder to use the publisher or vice-versa, but they are combined in one repository for ease of use.)
Building Plugins with the Builder
To build your plugin, you'll need a small file like this (named ophidian.config.mjs
by convention, but anything ending in .mjs
will work):
import Builder from "@ophidian/build";
new Builder("src/pane-relief.ts") // <-- the path of your main module
.withSass() // Could be omitted
.withInstall() // Optional: publish to OBSIDIAN_TEST_VAULT on build
.build();
This is the entire build configuration. You can do more complex things with it, but the basics are:
- You create the builder with the path of your plugin's main module (the one exporting the plugin class)
- You indicate whether you're using Sass, CSS, or neither. (For Sass, you'll
import
.css or .scss files in your code; for CSS you'll just put a styles.css in your repository root.) - You indicate whether you want builds to be copied to the correct directory under your
OBSIDIAN_TEST_VAULT
environment variable and hot-reloaded (if you have the hot-reload plugin installed in that vault). (Note: if you don't want to set the environment variable by hand, you can use an.envrc
file with direnv to set it automatically, or you can just symlink the plugin directory in your test vault to./dist
(or vice versa) and make sure there's a.hotreload
file in it.) - You tell it to build.
Now, how do you actually run it? You need to modify your package.json like so (changing the file name if needed):
{
"scripts": {
"dev": "node ophidian.config.mjs dev",
"build": "node ophidian.config.mjs production"
},
// ...
"devDependencies": {
"@ophidian/build": "^1",
// ...
}
}
Now, you can use your package manger (npm, yarn, or pnpm) to dev
(watch & rebuild with sourcemaps) or build
(one-time run with compressed code). (You'll also need to have your package manager install
your dev dependencies before you start.)
Regardless of build type, the output files are copied to dist/
under your project root, and optionally copied to your test vault. Note that because of the way esbuild Sass support works, you'll also see a spurious dist/main.css
file -- @ophidian/build then copies this file to the correct name of dist/styles.css
.
Publishing Plugins with the Github Action
The Ophidian Publish action makes updating your plugins on Github easy, even if you don't use Ophidian as a library or to build your plugin. Its features include:
- Automatically checking your manifest (or manifest-beta) version against the tag to make sure they match
- Automatically converting your most recent commit message to (markdown) notes on the release
- Using the newer of manifest.json or manifest-beta.json for the actual release, so you can release the beta generally just by pushing a new manifest.json in your repo.
- The built deliverables (main.js and styles.css) can live in the repo root, or a
dist/
orbuild/
subdirectory - A .zip file with the entire plugin is included in each release, for people to easily download and install the entire plugin if they need a specific version
And, perhaps the best part, it keeps your plugin action scripts short and sweet, e.g.:
name: Publish plugin
on:
push: # Sequence of patterns matched against refs/tags
tags:
- "*" # Push events to matching any tag format, i.e. 1.0, 20.15.10
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: ophidian-lib/build@v1
with:
token: ${{ secrets.GITHUB_TOKEN }}
release-notes: ${{ github.event.commits[0].message }}
Usage Requirements
Aside from having a .github/workflows/publish.yml
file like the above example, your plugin must have a build command that can be run via your package manager build
command. It should place the built main.js and styles.css (if applicable) in the repository root, or else dist/
or build/
. Files in the root take precedence over files found elsewhere; manifest.json
(and manifest-beta.json
if applicable) must always be in the repository root since Obsidian (and BRAT) look for them there.
If you have a manifest-beta.json, Ophidian will publish it in place of manifest.json, if it contains a higher version number. Whichever version is chosen must exactly match the tag you pushed (with git push --tags
) to deploy the new version, or the action will fail with an error.
Configuration
The action supports the following configuration variables, which you may need to change from the simple arrangment shown above:
token
- should be set as shown, it will be used to generate the release, upload files, and create release notesrelease-notes
should be set to what you want included in the release notes. Set as shown in the example unless you need something special. The first line of the string will be converted to an H3 heading (by adding###
and a space in front of it).package-manager
should be set topnpm
,npm
oryarn
to match your package lockfile (pnpm-lock.yaml
,package-lock.json
, oryarn.lock
). This is the command that will be used to run theinstall
andbuild
scripts for your plugin.build-script
can be set if you want the build to use a different package.json script thanbuild
(e.g.cibuild
,publish-plugin
, or something like that)node-version
can be set if you need a specific node.js version to run your builder; Ophidian targets Node 14 by default.pnpm-version
can be set if you need a specific version of pnpm. (The default is the latest version that supports Node 14.)
(Note: I am using this action mainly with pnpm; if you experience problems using npm or yarn, feel free to file an issue, ideally referencing the repo and/or branch that's giving you trouble so I can attempt to reproduce the problem.)
Additional Features
Inlining Text and CSS
As of version 1.2, you can now inline files as strings, using code like this:
// Both of these are strings from the files at build time
import someFile from "text:./someFile.whatever";
import someCSS from "scss:./some.scss"; // and scss is converted to css
If you want to use this feature, you'll probably want to add the following to one of your .d.ts files (e.g. global.d.ts
in your source folder):
declare module "scss:*" {
const value: string;
export default value;
}
declare module "text:*" {
const value: string;
export default value;
}
This will tell TypeScript and your IDE that what importing from these locations produces strings.