README
¶
fylr-build-plugin
The build driver for fylr plugins — the "make" that knows how a fylr plugin is put together. This README is also the reference for how a fylr plugin repository is structured and what a plugin can offer; the living example is fylr-plugin-example, which exercises every feature described here. Start a new plugin by copying its structure.
The tool is distributed as a versioned Go module, so a plugin repo carries no build machinery (no submodule, no vendored Makefile include):
go run github.com/programmfabrik/fylr-build-plugin@latest build
Plugin repos keep a thin Makefile shim for muscle memory (make build,
make zip, …) that just calls the tool.
Versioning: plugins call the tool with @latest, which resolves the
newest tagged release — a v1.0.1 reaches every plugin build automatically,
no plugin repo is touched. main can hold unfinished work; cutting a release
is pushing a vX.Y.Z tag. An incompatible change is released as a new major
version, which per Go's semantic import versioning gets a new module path
(github.com/programmfabrik/fylr-build-plugin/v2) — existing plugins keep
resolving the v1 line untouched and migrate by changing the one go run line
when they choose to.
The name follows the fylr convention: fylr-plugin-* is reserved for plugins,
tooling is named fylr-<verb>-plugin — this one builds plugins. It also
seals them: the former fylr-seal-plugin is merged in here, including the
pluginseal package that fylr imports to open sealed plugins.
A well-structured fylr plugin
One repo per plugin, named fylr-plugin-<name> (custom data types:
custom-data-type-<type>). fylr plugins are fylr-only: no easydb5 hybrid
code, and easydb-library must never be used.
Start a new plugin with fylr-build-plugin init in a fresh repo directory —
it scaffolds everything below (a buildable plugin with one example API
extension, webfrontend and loca) and refuses to run inside an existing plugin.
Existing files (a GitHub-created README.md, LICENSE, …) are kept and skipped.
fylr-plugin-example/
├── manifest.yml the plugin: identity + every feature wiring, read by
│ fylr — ships VERBATIM as build/<name>/manifest.yml
├── build.yml the build: explicit delivery lists for fylr-build-plugin
├── Makefile thin shim: make help/build/zip/seal/loca/check/clean
├── README.md plugin docs; the zip ships a self-contained copy
├── LICENSE
├── .github/workflows/
│ └── release.yaml release build, from templates/ (public or private)
├── .gitignore build/, compiled JS, .DS_Store — generated files are
│ NEVER committed, dev and CI compile from source
├── l10n/
│ └── example-loca.csv localization, mastered in Google Sheets ("fylr
│ localization" sheet, one tab per plugin), pulled
│ with `make loca` — never edited by hand
├── server/ server-side programs (node / python3 / Go), wired in
│ the manifest as extensions and callbacks
│ └── extension/hello/ a Go module: cross-compiled by the build, sources
│ never ship
├── fas_config/ asset-server config: cookbooks + produce config
├── webfrontend/ frontend sources and assets (= base_url_prefix)
│ ├── *.coffee compiled into the plugin.webfrontend.url bundle
│ ├── lib/*.js vendored JS, a source of that same bundle
│ ├── *.scss compiled to same-named .css
│ └── *.css/.html/img delivered as-is (build.yml webfrontend.install)
└── build/ generated by `build`, gitignored:
└── fylr_example/ the plugin as fylr loads it — manifest.yml,
build-info.json, compiled JS/CSS/binaries, copies
The folder build/<plugin.name>/ is the plugin in its installed form: fylr
loads it directly from disk during development, and the release zip is exactly
this tree (top-level folder = plugin.name, which fylr enforces on install —
the name comes from the manifest, not the repo).
What a fylr plugin can offer
Every feature is declared in manifest.yml; the
example's manifest
exercises all of them. Server-side programs are wired the same way everywhere:
fylr runs them via its exec services (node, python3, or exec for
compiled binaries), passing the request on stdin and reading the response from
stdout; %_exec.pluginDir% resolves to the installed plugin folder,
%info.json% passes fylr config + call context, and %_exec.GOOS% /
%_exec.GOARCH% select the right cross-compiled binary. A callback can run
with an api token (plugin_user) to call back into the fylr API.
| Manifest section | Feature |
|---|---|
plugin |
identity: name, version, displayname, plus the l10n CSV and the webfrontend entry points (url JS bundle, css, html) |
base_url_prefix |
where the webfrontend files are served from (by convention the webfrontend/ folder) |
extensions |
plugin API endpoints served under fylr's API, each backed by an exec program |
callbacks |
hooks into fylr flows: db_pre_save (an ordered steps list with objecttype filters — validate or modify objects before save), transition_db_pre_save, export, export_transport |
collection_upload |
hooks into collection uploads (api / hotfolder), with per-hook config parameters |
base_config |
plugin settings that appear in fylr's base config UI and /api/config, typed parameters |
system_rights |
plugin-defined system rights with typed parameters (bool, int, text, string-list*, mask-select, objecttype-select, eas-column-select, pool-select, preview-versions) |
custom_types |
custom data types: index mapping (text, number, geo, …, incl. skipTerms), per-schema/mask config, and a batched update callback |
fas_config |
asset production: a produce config and cookbooks merged into the fylr asset server |
custom_events |
plugin-defined event types |
Localization: the plugin.l10n CSV has a key column and one column per
language (de-DE, en-US, …); extra sheet columns (fil, the R TODO
checkboxes) are ignored by fylr's loader, so the Google Sheets export is
committed as-is.
Next to the manifest, the build writes build-info.json (repository,
rev, release, lastchanged, builddate) — fylr's plugin manager shows
it, so an installed plugin is traceable to a commit and release.
Commands
| Command | Does |
|---|---|
init |
scaffold a new plugin into the current (fresh) directory |
build |
assemble build/<plugin.name>/ — loadable by fylr from disk |
zip |
build + release zip |
seal |
seal a plugin zip for the marketplace (public key only) |
genkey |
generate a seal recipient keypair |
info |
inspect a (sealed) plugin zip: name, sealed?, recipient |
loca |
pull loca CSV(s) from their Google Sheets master |
readme |
write a self-contained README (relative images inlined) |
check |
validate the build tree against the manifest |
clean |
remove the build folder |
notify-release |
tell the marketplace catalog about a published release |
All commands run from the plugin repo root (where manifest.yml lives).
External tools are checked per step with an actionable error: coffee is only
required when the plugin has CoffeeScript, sass only for SCSS, go only for
Go server extensions, uv only for Python
packages.
The tool reads no environment variables — every input is a flag. Where a
release workflow has a value in env (RELEASE_TAG), the plugin's Makefile
shim translates it into the -release flag. The one exception is the token of
notify-release, GH_TOKEN: a secret must not show in the process list.
How the release zip is named
The zip is always build/<repo>.zip, named after the repository. This is
a rule of the tool, hard-wired: there is no flag, no env var and no per-repo
exception.
A release url then reads as one piece, and can be written down without looking anything up:
https://github.com/programmfabrik/<repo>/releases/latest/download/<repo>.zip
The manifest's plugin.name is deliberately not used. The two diverge
often enough — fylr-plugin-scancode-display ships the plugin
fylr-scancode-display, fylr-plugin-custom-data-type-k10plus ships
custom-data-type-gvk — that a manifest-derived asset would sit at a url that
disagrees with itself. plugin.name is also editable in a way the repository
is not: renaming it would silently move the release asset.
Inside the zip the top-level folder stays the plugin name, which fylr requires; it is unaffected by the name of the file it arrives in.
The repository is taken from the origin remote, falling back to the
directory name. The shipped release workflows attach build/*.zip, so they
never restate the rule.
What build does
The delivered files are listed explicitly in build.yml — nothing is
derived from the manifest, since a derived list is easily incomplete. The
safety net is check, which runs with every build and validates the assembled
tree against every path the manifest references — a dangling reference is
reported as a warning (it can be deliberate, e.g. the example plugin's
missing-module test callbacks).
-
manifest.ymlis copied verbatim tobuild/<name>/manifest.yml(no master/generated split;plugin.namein the manifest names the build folder and the zip's top-level dir, which fylr enforces on install). -
server.installandwebfrontend.installentries (files or dirs) are copied verbatim..DS_Store,.gitignore,.git,node_modulesnever ship. -
server.bundlesandwebfrontend.bundlesentries are assembled: sources concatenated in the order written, each handled by its extension (.coffeecompiled with CoffeeScript 1.x — the version the plugins are stuck on —.scsscompiled, anything else verbatim). A webfrontend entry withoutoutwritesplugin.webfrontend.url, the only bundle fylr loads, so a vendored library that is not CoffeeScript (a viewer, a charting lib) has to be part of it — delivered next to the bundle it would never be loaded. -
webfrontend.scssfiles compile to same-named.css. -
npm dependencies of the plugin's node programs are resolved into the delivered files: every
%_exec.pluginDir%/….jsthe manifest runs has itsrequires followed and the reached modules inlined, node's builtins left alone. Nothing configures this — declare the dependency inpackage.json, commitpackage-lock.json, and the build runsnpm ciwhen needed.node_modulesnever ships, so this is what makes a dependency work at all; a program that requires nothing is delivered byte-for-byte as written. -
Python packages of the plugin's python3 programs are listed in
build.yml, per folder:server: python: - dir: server/extension/python_dep # delivered by server.install packages: # as pip takes them, "trimesh>=4" too - python-slugify - trimeshThe build resolves them with
uvfor the fylr image — Python 3.14 on Linux, whatever machine builds, so a dependency behind a marker likepython_version >= "3.13"is decided the way it is on the instance — and installs every resolved package, dependencies included, into that folder of the build tree. Python looks into a program's own folder first, so the programs thereimportthem without any setup; a program in another folder does not see them. Nothing runs pip on an instance or an execserver: the packages travel in the zip, with their.dist-info, which records the version that shipped.Only pure-Python packages ship. A compiled one is built for one Python and one platform, and the image's Python moves with Debian, so compiled packages come from the fylr image, which installs them explicitly:
numpyandopencv-python. They are resolved capped at the version the image has, so a dependency that needs a newer one fails the build, and any other compiled package fails it too — it has to be added to the fylr image first. A fylr outside the image (a developer's own) runs the programs with its ownpython3, which then needs a version the packages accept (Requires-Python) and those compiled packages installed. -
server.go.modulescross-compile for every configured arch (CGO off, trimmed, stripped) into theirexetemplate —%GOOS%/%GOARCH%replaced, matching the manifest's%_exec.GOOS%/%_exec.GOARCH%references. Go sources do not ship. -
build-info.jsonis written beside the manifest:repository,rev,release(from-release; the release workflow's tag reaches the tool via the Makefile),lastchanged,builddate. -
checkruns automatically: every manifest reference (%_exec.pluginDir%/...exec programs,plugin.l10n,plugin.webfrontend.*,fas_configfiles) should exist in the build tree; cross-compiled references are checked for every configured arch, commented-out manifest blocks do not count. Missing references are warnings, not errors.
Development loop
build produces an on-disk plugin. In the fylr server's fylr.yml:
plugin:
paths+:
- ../my-plugin/build
Point at build/, not the repo root — fylr walks the path for any
manifest.yml, and the root manifest would collide with the built one.
build.yml
The explicit build description. Unknown keys are rejected. Every feature is exercised by fylr-plugin-example's build.yml.
server: # the non-webfrontend side: l10n and fas_config too
install: # server-side delivery, copied verbatim
- server
- fas_config
- l10n
bundles: # assembled server-side files (see Bundles below)
- out: updater/DANTEUpdater.js
sources:
- src/updater/DANTEUpdater.js
- webfrontend/DANTEUtil.coffee
go: # Go server extensions, cross-compiled
archs: # each entry sets Go's GOOS/GOARCH build env;
- { GOOS: linux, GOARCH: amd64 } # optional — default: every
- { GOOS: darwin, GOARCH: arm64 } # platform fylr runs on
modules:
- dir: server/extension/hello
exe: server/extension/hello/hello-%GOOS%-%GOARCH%.exe
webfrontend:
bundles: # no out -> plugin.webfrontend.url, the bundle fylr
- sources: # loads; sources in the order written
- webfrontend/lib/vendor.js # verbatim
- webfrontend/MyClass.coffee # compiled (CoffeeScript 1.x)
- webfrontend/UsesMyClass.coffee
scss: # compiled to same-named .css
- webfrontend/MyStyle.scss
l10n_json: # loca CSV -> per-culture JSONs the webfrontend
- csv: l10n/my-loca.csv # loads (easydb-library l10n2json format),
out: l10n # written under base_url_prefix (default l10n)
install: # delivered as-is: plain css, html, images, fonts
- webfrontend/MyPlugin.html
- webfrontend/MyPlugin.css
loca: # Google Sheets masters for the loca command
- csv: l10n/my-loca.csv
sheet: <spreadsheet key>
gid: "<tab gid>"
zip_aliases: # historical asset names (see below)
- customDataTypeDante.zip
Bundles
A bundle is one file assembled from an ordered list of sources. Every file a
plugin ships runs in one of two places, so bundles are declared on that side:
server.bundles for what node runs (and for l10n, which is delivered there
too), webfrontend.bundles for browser code. A webfrontend entry may leave
out empty, meaning plugin.webfrontend.url — the common case then does not
restate a path the manifest already owns. The sides are validated against
base_url_prefix, so a bundle cannot land on the wrong one by accident.
Sources are concatenated in the order written, each handled by its
extension (.coffee and .scss compiled, anything else verbatim), and two
sources are never glued together — a source not ending in a newline gets one.
Order being the author's matters: the custom-data-type updaters need a hand-written Node script first with the shared utility appended, while a plugin vendoring a library may need it evaluated before its own code.
out is any path inside the plugin folder, so a bundle is not limited to
JavaScript — it also covers concatenating several CSS files into the one the
manifest declares, or appending a second CSV to an l10n file. Bundles run after
install, so a bundle may overwrite a file that was copied in verbatim.
npm dependencies
node_modules never ships. A require("pg") in a server program therefore has
nothing to resolve against on the instance, which is why the build resolves it
at build time: for every node program the manifest runs
(%_exec.pluginDir%/….js), the requires are followed from that file and the
reached modules are inlined into it, while node's builtins stay real requires.
There is no key for this. Declare the dependency in package.json and commit
package-lock.json; the build installs (npm ci) when node_modules is
missing or older than the lockfile. It applies to assembled files too — an
updater built by server.bundles is a node program like any other. A file
whose module graph is only itself is left exactly as delivered.
Native modules (node-gyp: pg-native, sharp) cannot be bundled and are
host-specific — a plugin must not depend on them. An unresolvable require fails
the build rather than shipping a program that dies on its first call.
Historical asset names
A published asset name can never be retired, only added to. fylr updates a url plugin by re-fetching the url it stored at install time — not by re-reading the marketplace catalog — so an instance that installed while the zip had a different name holds that url forever. Dropping the name breaks its updates silently, and the instance has no way to discover the new one.
Any repo whose asset name has changed — every plugin migrated here from a hand-written Makefile, which named its zip whatever it liked — lists its previous names and keeps publishing them:
zip_aliases:
- customDataTypeDante.zip
zip writes each alias as a byte-identical copy beside the real zip. The
release workflows attach build/*.zip, so the copies reach the release without
the workflow having to know they exist.
Loca
Plugin loca CSVs are mastered in Google Sheets (fylr's "fylr localization"
sheet, one tab per plugin) and pulled with fylr-build-plugin loca — never
edited locally. The raw export (with the fil ticket column and R TODO
checkboxes) is committed as-is; fylr's CSV loader only reads the key column
and xx-XX language columns.
Sealing
A sealed plugin is still a valid zip: the plugin folder with a plaintext
manifest.yml, the whole plugin encrypted to fylr's public key beside it
(fylr-sealed-plugin.enc, X25519 + XSalsa20-Poly1305 sealed box). Only a fylr
holding the matching private key can open and run it.
fylr-build-plugin seal # builds the zip if needed, dev/CI key
fylr-build-plugin seal -pubkey <base64> # production / marketplace-source key
fylr-build-plugin genkey # fresh keypair
fylr-build-plugin info my-plugin_sealed.zip
Sealing uses a public key only — no secrets in CI. With no -pubkey the
dev/CI key is used: such a plugin opens only on a fylr built with
-tags licensetest, which is what makes a public example
(fylr-plugin-example-licensed)
safe to publish. fylr opens sealed plugins via the pluginseal
package — sealer and server share one source of truth and cannot drift:
plain, sealed, err := pluginseal.OpenPluginZip(artifact, keysThisBuildHolds...)
Release workflows
A release is cut by a manager on the GitHub release page; the workflow builds and publishes the artifact. Two templates live in templates/:
- release-public.yaml — attach the zip to
the release; fylr installs from
releases/latest/download/<repo>.zip. - release-private.yaml — additionally publish to GitHub Pages under an unguessable per-repo UUID URL, since a private repo's release assets are not fetchable by fylr.
Either variant becomes a sealed release by switching make zip to
make seal — no secrets needed.
Both end with a marketplace job: once the zip is reachable, it runs
fylr-build-plugin notify-release, which sends the repository dispatch
plugin-released to this repository. Its
marketplace-releases workflow
then writes the plugin's latest release (tag, date, sha256) into the fylr
Plugin Marketplace catalog, so instances limited to marketplace plugins follow
the release within minutes. The same workflow runs every 6 hours for all
plugins and catches releases whose workflow does not notify; zip and seal
warn about such a workflow. The token is the organization secret
FYLR_BOT_PERSONAL_ACCESS_TOKEN; outside the programmfabrik organization it is
empty, and notify-release only prints a notice.
readme
Writes a self-contained README: every relative image reference is inlined
as a data: URI. This matters because most plugin repositories are private —
once a README leaves the repo (into the plugin zip, then the marketplace) its
relative asset paths are unreachable. build bundles it automatically as
build/<name>/README.md.
build delivers it as build/<name>/README.md — next to manifest.yml, the
one place fylr reads a plugin's docs: the marketplace reads it out of the
release zip via HTTP range requests, and (since #80537) the plugin manager
shows it as the installed plugin's README tab. No manifest key is involved;
shipping the file is enough. The retired plugin.webfrontend.readme key is
rejected by build — remove it from old manifests.
fylr-build-plugin readme [flags]
--in input markdown file (default "README.md")
--out output self-contained markdown file (default "build/README.md")
--max-image-bytes leave images larger than this many bytes as relative links (default 524288)
Documentation
¶
Overview ¶
Command fylr-build-plugin is the build driver for fylr plugins — the "make" that knows how a fylr plugin is put together. It is run from a plugin repo's root without a submodule or vendored include, e.g.
go run github.com/programmfabrik/fylr-build-plugin@latest build
It assembles build/<plugin.name>/ (loadable directly by fylr via plugin.paths), zips it for release, and can seal the zip for the fylr Plugin Marketplace (the former fylr-seal-plugin, merged here — the pluginseal package is imported by fylr to open sealed plugins).
The name follows the fylr convention: "fylr-plugin-*" is reserved for plugins, tooling is "fylr-<verb>-plugin".
Sealing (the former fylr-seal-plugin, merged here): a sealed plugin is still a valid zip that keeps the plugin folder with a plaintext manifest, the whole plugin encrypted to fylr's public key beside it. Sealing uses a PUBLIC key only, so it runs in any (public) build pipeline without a secret; the private key lives in fylr. fylr imports the pluginseal package to open sealed plugins — one source of truth, no drift.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package pluginseal seals a fylr plugin zip into a "sealed plugin" — still a valid zip — and opens one back.
|
Package pluginseal seals a fylr plugin zip into a "sealed plugin" — still a valid zip — and opens one back. |