---

KiriBuild

The reusable GitHub Action for Kirigami projects — ensure Node 24+ and the kiri CLI, then export.

---

Overview

KiriBuild is a lightweight composite GitHub Action that prepares the toolchain a Kirigami project needs and runs its production export:

• Node 24+ on demand — if the runner already has Node.js 24 or newer, it's left untouched; otherwise the requested version is installed.
• Local CLI first — uses your project's own kiri (node_modules/.bin/kiri, installed by @kirigami/cli, or by @kirigami/kirigami before 3.0.0) when present, and installs @kirigami/cli globally only when it isn't.
• One-command export — runs kiri export with the WebAssembly flag @kirigami/php-wasm requires.

Checkout, Git LFS, and committing or deploying the exported files are left to your workflow, so you stay in control of what happens around the export.

Published on the GitHub Marketplace — search "KiriBuild" from a workflow file's Actions sidebar, or reference php-kirigami/kiribuild@v2 directly as shown below.

---

Table of contents

• KiriBuild
  • Overview
  • Table of contents
  • Requirements
  • Usage
  • Full example — deploy to GitHub Pages
  • What it does
  • Inputs
  • Outputs
  • Local testing
  • License
  • Author

---

Requirements

• A workflow that has already checked out the repository (actions/checkout).
• Network access to the npm registry (for the CLI install / project dependencies).

---

Usage

- name: Checkout
  uses: actions/checkout@v7

- name: KiriBuild
  uses: php-kirigami/kiribuild@v2
  with:
    node-version: '24'

---

Full example — deploy to GitHub Pages

name: Deploy to GitHub Pages

env:
  TZ: America/Toronto

on:
  push:
    branches: ["main"]
  workflow_dispatch:

permissions:
  contents: write
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: true

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:

      - name: Checkout
        uses: actions/checkout@v7
        with:
          lfs: true

      - name: KiriBuild
        uses: php-kirigami/kiribuild@v2
        with:
          node-version: '24'

      - name: Commit exported files
        shell: bash
        run: |
          if [ -n "$(git status --porcelain)" ]; then
            git config user.name "kirigami[bot]"
            git config user.email "[email protected]"
            git add -A
            git commit -m "chore: update exported files [skip ci]"
            git push
          else
            echo "No changes to commit."
          fi

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v5
        with:
          path: dist

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v5

---

What it does

1. Check for Node 24+ — if the runner already has Node.js 24 or newer, nothing happens.
2. Setup Node — only when the check above fails, installs the requested Node.js version (actions/setup-node@v7).
3. Install project dependencies — only when a package.json is present, and skipped if node_modules/ is already there. Uses npm ci when a package-lock.json (or npm-shrinkwrap.json) is committed — so a checked-in lockfile is never rewritten by the build — and falls back to npm install otherwise.
4. Ensure the Kirigami CLI is available — if node_modules/.bin/kiri exists it's used as-is; otherwise @kirigami/cli is installed globally so kiri is always on PATH (or @kirigami/kirigami, when the legacy kirigami-version input is set). A project that depends on @kirigami/kirigami without @kirigami/cli gets a warning: the global kiri then runs its own engine version rather than the project's.
5. Export — runs kiri export (adding the --experimental-wasm-jspi Node flag on Node versions that still need it, i.e. Node 24), preferring the project's local kiri binary over the global one.

---

Inputs

Name	Description	Required	Default
node-version	Node.js version to install if the runner does not already have Node 24+	false	24
cli-version	Version of @kirigami/cli to install globally when the project has no local kiri	false	latest
kirigami-version	Legacy: install this @kirigami/kirigami version globally instead of @kirigami/cli. Only versions before 3.0.0 ship kiri	false	(empty)

Since @kirigami/kirigami 3.0.0, the kiri command lives in @kirigami/cli. The recommended setup is to add @kirigami/cli to the project's devDependencies, so the action uses the locally pinned CLI.

---

Outputs

This action has no outputs. Artifact upload, commits, and deployment are left to your own workflow, so you stay in control of what happens to the exported files.

---

Local testing

.github/workflows/test.yml has two jobs, both on every push / PR:

• cli-resolution — runs the tiny fixture in test/fixtures/site through every CLI-resolution branch (local-cli, local-cli-package, global-cli, preinstalled, lockfile, has-node-24, pinned-version, plus a non-blocking latest-canary), and checks the core Kirigami feature surface on each: layouts, a data file, a Markdown block, a custom tag + render hook, and the image autogenerator.
• templates — runs the action against the official template-default and template-demo, covering the @kirigami/canva Sass pipeline, esbuild and the highlight plugin.

Run them locally with act:

act push -j cli-resolution
act push -j templates

---

License

This project is distributed under the MIT license.

---

Author

MIT © Maxime Larrivée-Roy, 2026