# Building and publishing native Parcel plugins `parcel-bundler/parcel/.github/workflows/native-plugin.yml` is a reusable GitHub Actions workflow that builds a native Parcel plugin — written in Rust, Go, or Swift — for every platform it declares, and publishes the results to npm. A native plugin is published as one package per platform, plus a plugin package that depends on all of them as `optionalDependencies`. npm installs only the artifact package matching the host's `os`, `cpu`, and `libc`, so users download one binary instead of seven. The workflow derives all of that from a single `parcel` key in your package.json. ## Your package.json ```json { "name": "@devongovett/parcel-transformer-ts-doc", "description": "Parcel v3 transformer for typescript documentation", "version": "1.0.0", "license": "MIT", "repository": "https://github.com/devongovett/ts-doc-rs", "engines": { "parcel": "^3.0.0-0" }, "parcel": { "abi": 1, "artifacts": { "aarch64-apple-darwin": "@devongovett/parcel-transformer-ts-doc-darwin-arm64", "x86_64-apple-darwin": "@devongovett/parcel-transformer-ts-doc-darwin-x64", "x86_64-pc-windows-msvc": "@devongovett/parcel-transformer-ts-doc-win32-x64-msvc", "x86_64-unknown-linux-gnu": "@devongovett/parcel-transformer-ts-doc-linux-x64-gnu", "aarch64-unknown-linux-gnu": "@devongovett/parcel-transformer-ts-doc-linux-arm64-gnu", "x86_64-unknown-linux-musl": "@devongovett/parcel-transformer-ts-doc-linux-x64-musl", "aarch64-unknown-linux-musl": "@devongovett/parcel-transformer-ts-doc-linux-arm64-musl" } } } ``` - `engines.parcel` — the range of Parcel versions your plugin supports. Parcel refuses to load a plugin whose range its version does not satisfy, and warns about one without a range. `^3.0.0-0` includes the Parcel 3 prereleases, which `^3.0.0` does not. - `parcel.abi` — the Parcel plugin ABI version your plugin builds against. The workflow refuses to publish one that differs from the ABI of the Parcel release it comes from. - `parcel.artifacts` — one entry per platform you want to ship, mapping a Rust target triple to the npm package name its binary is published under. The build matrix is these keys; add or remove a line to add or drop a platform. An artifact can also be a relative path to a library inside the plugin package itself, e.g. `"./plugin-darwin-arm64.dylib"`. That ships every platform in one package instead of one per platform — simpler for a small plugin, at the cost of every user downloading every binary. This workflow always builds the per-platform form; the path form is meant for plugins that don't need to publish this way. Nothing in that file says which language the plugin is written in, and nothing needs to: `parcel.artifacts` is keyed by the target triple **Parcel** was built for, which is what picks the artifact to load at runtime. A Go or Swift plugin's package.json has exactly this shape. The workflow detects the toolchain from the plugin directory — `Cargo.toml` means Rust, `go.mod` means Go, `Package.swift` means Swift — or takes the `language` input if a directory has more than one. ## Developing a plugin The artifact packages only exist once you have published, which is awkward while you are still writing the plugin. Point `parcel.devLibrary` at your local build instead: ```json "parcel": { "abi": 1, "artifacts": { "…": "…" }, "devLibrary": "./target/debug/libmy_plugin" } ``` Parcel loads that in place of the artifact for the current platform, so a `.parcelrc` can name the plugin the way consumers will — `"@acme/my-plugin"` — with no edit-and-revert cycle before publishing. Leave the extension off and Parcel appends this platform's, so one entry works for everyone regardless of what they build on. It wins over `artifacts` outright rather than acting as a fallback, and if the file is missing the build fails saying so. Falling back would mean a stale published binary loading while your changes appear to do nothing. This is safe because the workflow **strips `devLibrary` when it publishes**, so a package that has it is by definition a working tree rather than something a consumer installed. A Rust plugin's `Cargo.toml` must build a `cdylib`: ```toml [lib] crate-type = ["cdylib"] ``` A Go plugin needs nothing beyond its `go.mod`; the workflow builds it with `go build -buildmode=c-shared`, which requires cgo and therefore a C compiler for the target. That is supplied for you — see the targets table below. A Swift plugin's `Package.swift` must declare a dynamic library product, which is what `swift build` produces as `lib.dylib` / `.so`: ```swift products: [.library(name: "MyPlugin", type: .dynamic, targets: ["MyPlugin"])], ``` Point `devLibrary` at `./.build/debug/libMyPlugin` while developing. If the package declares several dynamic libraries, name the plugin with the `swift-product` input. See [Swift](#swift) for which targets Swift plugins support. ## Using the workflow ```yaml name: release on: push: tags: ['v*'] jobs: release: permissions: contents: read id-token: write # required for npm trusted publishing uses: parcel-bundler/parcel/.github/workflows/native-plugin.yml@v3 with: paths: . publish: true ``` To use it as a build check on pull requests, call it the same way with `publish: false` (the default). Everything except the publish step runs, and the tarballs are uploaded as workflow artifacts so you can download and inspect exactly what would have been published. ## Monorepos Pass every plugin to a single call rather than calling the workflow once per plugin: ```yaml jobs: release: permissions: contents: read id-token: write uses: parcel-bundler/parcel/.github/workflows/native-plugin.yml@v3 with: paths: | packages/transformer-a packages/transformer-b publish: true ``` Calling the workflow once per plugin does not work. All calls in a workflow run share one artifact namespace, so the uploads collide, and the publish step would find another plugin's tarballs alongside its own. ### Inputs | Input | Default | Description | | ---------------- | --------------- | ----------------------------------------------------------------- | | `paths` | `''` | Directories containing the `package.json` and `Cargo.toml` files. | | `publish` | `false` | Publish to npm once every target has built successfully. | | `version` | `''` | Version to publish, overriding `version` in each package.json. | | `tag` | derived | npm dist-tag. Defaults to the prerelease identifier, or `latest`. | | `language` | detected | `rust`, `go`, or `swift`. Detected from the manifest when empty. | | `rust-toolchain` | `stable` | Rust toolchain to build with. | | `go-version` | `stable` | Go version to build with. | | `go-args` | `''` | Extra arguments for `go build`, e.g. `-tags foo`. | | `cargo-args` | `''` | Extra arguments for cargo, e.g. `--features foo`. | | `swift-version` | `6.2` | Swift for Linux builds: the `swift:-amazonlinux2` image. | | `xcode-version` | `latest-stable` | Xcode for macOS Swift builds, via `maxim-lobanov/setup-xcode`. | | `swift-product` | `''` | Dynamic library product to build, when there is more than one. | | `swift-args` | `''` | Extra arguments for `swift build`, e.g. `-Xswiftc -DFOO`. | | `rustflags` | `''` | Extra `RUSTFLAGS`. See the note on musl below. | | `node-version` | `24` | Node.js version used for packaging and publishing. | | `zig-version` | `0.14.0` | Zig version used by `cargo-zigbuild` for Linux targets. | ### Outputs `name`, `version`, and `language` of the plugin package that was built. They are empty when several plugins were built in one run, rather than describing an arbitrary one. ## Publishing Publishing uses [npm trusted publishing](https://docs.npmjs.com/trusted-publishers), so there is no npm token to create or rotate. Before your first release, configure a trusted publisher on npmjs.com for **every** package the workflow publishes — the plugin package and each artifact package — pointing at your repository and the workflow file that calls this one. The calling job must also grant `id-token: write`, as above. Artifact packages are published before the plugin package, so the plugin is never resolvable before the binaries its `optionalDependencies` pin. Versions already on npm are skipped, so a run that failed partway through publishing can simply be re-run. ## Supported targets | Rust target | Runner | Built with | os | cpu | libc | | ------------------------------- | ---------------- | -------------- | ------ | ----- | ----- | | `aarch64-apple-darwin` | `macos-latest` | cargo | darwin | arm64 | | | `x86_64-apple-darwin` | `macos-latest` | cargo | darwin | x64 | | | `aarch64-pc-windows-msvc` | `windows-latest` | cargo | win32 | arm64 | | | `x86_64-pc-windows-msvc` | `windows-latest` | cargo | win32 | x64 | | | `x86_64-unknown-linux-gnu` | `ubuntu-latest` | cargo-zigbuild | linux | x64 | glibc | | `aarch64-unknown-linux-gnu` | `ubuntu-latest` | cargo-zigbuild | linux | arm64 | glibc | | `x86_64-unknown-linux-musl` | `ubuntu-latest` | cargo-zigbuild | linux | x64 | musl | | `aarch64-unknown-linux-musl` | `ubuntu-latest` | cargo-zigbuild | linux | arm64 | musl | Apple and Windows targets build on their native runners. Linux targets are cross compiled with `cargo-zigbuild`; glibc targets link against glibc 2.26 so the binaries run on distributions older than the runner image. musl targets are built with `RUSTFLAGS=-C target-feature=-crt-static`. musl links the CRT statically by default, and a static CRT cannot produce a dynamic library, so without it cargo refuses the build outright: ``` error: cannot produce cdylib for `your-plugin` as the target `x86_64-unknown-linux-musl` does not support these crate types ``` Because cargo lets `RUSTFLAGS` shadow `build.rustflags` rather than merging them, any flags you set in `.cargo/config.toml` are ignored on musl targets. Pass them through the `rustflags` input if you need them there — it is prepended to the target's own flags. To add a target, add it to [`targets.mjs`](targets.mjs). ### Swift Swift plugins can be built for four of these targets: | Rust target | Runner | Built with | | --------------------------- | ------------------ | ----------------------------------------------- | | `aarch64-apple-darwin` | `macos-latest` | `swift build --arch arm64` | | `x86_64-apple-darwin` | `macos-latest` | `swift build --arch x86_64` | | `x86_64-unknown-linux-gnu` | `ubuntu-latest` | `swift build` in `swift:-amazonlinux2` | | `aarch64-unknown-linux-gnu` | `ubuntu-24.04-arm` | `swift build` in `swift:-amazonlinux2` | macOS libraries link the Swift runtime that ships with macOS. The Swift SDK needs macOS 15 or later. Linux has no system Swift runtime, so Linux libraries are linked with `-static-stdlib` to carry their own. The build fails if the library still links the runtime dynamically. They are built natively in the official Amazon Linux 2 image, whose glibc 2.26 is the same floor the Rust and Go builds target through Zig. The build mounts the whole checkout into the container, so a path dependency elsewhere in the repository resolves too. Plugins in other repositories depend on the SDK by URL; see `plugin-swift/README.md`. musl and Windows targets aren't supported yet. Swift's static Linux SDK links musl itself into what it builds, which can't work for a library loaded into a musl process, and Windows needs the Swift runtime DLLs shipped alongside the plugin. The matrix step names any of these targets listed in `parcel.artifacts` and stops. ## What gets published For each target the workflow copies the cdylib to `plugin.` and generates a package.json from yours: same metadata, the artifact package's name, and the npm `os`/`cpu`/`libc` fields for that platform. ```json { "name": "@devongovett/parcel-transformer-ts-doc-darwin-arm64", "description": "Parcel v3 transformer for typescript documentation", "version": "1.0.0", "license": "MIT", "repository": "https://github.com/devongovett/ts-doc-rs", "os": ["darwin"], "cpu": ["arm64"], "files": ["plugin.dylib"], "parcel": { "abi": 1, "library": "plugin.dylib" } } ``` Fields that describe your wrapper package's own code — `scripts`, dependencies, `main`, `exports`, `bin`, `private`, `workspaces`, and similar — are dropped, since an artifact package contains nothing but the binary. Your own package is published as-is apart from `optionalDependencies`, which the workflow adds with an exact-version entry for each artifact package, and `parcel.devLibrary`, which it drops. Your checked-in package.json is not modified: the edit is made against a temporary copy while packing. ### Keeping Rust sources out of your package `npm pack` runs in your plugin directory, so by default it ships everything there that is not gitignored — including `Cargo.toml`, `Cargo.lock`, and `src/`. Your package does not need any of it: the binaries live in the artifact packages, and all your package contributes is metadata pointing at them. Add this to your package.json: ```json "files": [] ``` npm always includes `package.json`, `README`, and `LICENSE` no matter what `files` says, so an empty list publishes exactly those three and nothing else. Unlike an `.npmignore`, it stays correct as the crate grows. If you do ship something alongside the binaries — type definitions, a JS shim — list those files instead. Artifact packages are unaffected either way: each is staged in a temporary directory containing only the cdylib and its generated package.json. ## Scripts The workflow runs these directly; they are also runnable locally. - [`matrix.mjs`](matrix.mjs) — prints the build matrix derived from `parcel.artifacts`, and detects the plugin's language. - [`cargo-library.mjs`](cargo-library.mjs) — resolves which file cargo produced. The one Rust-specific step; a Go build already knows, having named it with `-o`. - [`swift-product.mjs`](swift-product.mjs) — picks the dynamic library product to build from `swift package dump-package` output. Swift names the library after it, and `swift build --show-bin-path` says where it is. - [`pack-artifact.mjs`](pack-artifact.mjs) — packs one target's library into a tarball. - [`pack-main.mjs`](pack-main.mjs) — packs the plugin package with `optionalDependencies`, failing if any declared target is missing a build. - [`publish.mjs`](publish.mjs) — publishes tarballs, each after any of the others it depends on and under the dist-tag its version calls for, skipping versions already on npm. - [`dist-tag.mjs`](dist-tag.mjs) — chooses that dist-tag: the `tag` input if set, else the prerelease identifier (`1.0.0-alpha.3` → `alpha`), else `latest`. - [`targets.mjs`](targets.mjs) — the supported target registry. - [`plugin-package.mjs`](plugin-package.mjs) — package.json validation and generation. ```sh node matrix.mjs --dir path/to/plugin node pack-artifact.mjs --dir path/to/plugin --target aarch64-apple-darwin \ --library path/to/libplugin.dylib --out ./artifacts node pack-main.mjs --dir path/to/plugin --artifacts ./artifacts --out ./main node publish.mjs ./artifacts/*.tgz ./main/*.tgz ``` `cargo-library.mjs` reads the JSON stream from `cargo build --message-format json-render-diagnostics`, which is how a Rust build locates the cdylib cargo produced rather than guessing its path. Everything downstream of that takes a plain `--library` path and does not care what built it.