Get started
Build a graft when Orchard is missing something your team needs. In this guide, you scaffold a graft, run it against your local Orchard, and pack it into a signed file that any instance can install.
A graft is a folder with a graft.json. It can also have a NestJS module for the API, a Svelte island for the UI, SQL migrations, and MCP tools. The graft command in @orchardlabs/graft-sdk builds, packs, and signs it.
Prerequisites
Section titled “Prerequisites”- Node.js and pnpm.
- A local Orchard dev stack. To set one up, follow Getting set up in the repository’s contributing guide.
1. Scaffold a graft
Section titled “1. Scaffold a graft”npx -p @orchardlabs/graft-sdk graft init snippetscd snippetspnpm installThe command creates these files:
snippets/ graft.json what the graft is and what it asks for package.json README.md server/src/index.ts NestJS module, default export ui/src/client.ts defineGraft({ slots, screens }) ui/src/Home.svelte migrations/0001_init/migration.sql tsconfig.json2. Run the graft
Section titled “2. Run the graft”In the graft’s folder, run the following command:
graft devThe command builds into .graft-dev/ and rebuilds when a file changes.
Start the Orchard server and frontend with these variables:
ORCHARD_GRAFTS_DIR=/path/to/snippets/.graft-dev ORCHARD_GRAFTS_DEV=1ORCHARD_GRAFTS_DEV skips signature checks for local work.
The graft’s pages are at http://localhost:4000/snippets, and its API is at /apiv1/snippets/.... Instance admin > Grafts shows its status.
UI changes appear when you reload the page. Restart the API server to pick up server changes and new migrations.
3. Check, pack, and sign
Section titled “3. Check, pack, and sign”graft doctorgraft keygen ~/.config/graft/key.pemgraft pack --key ~/.config/graft/key.pemgraft doctor checks graft.json and the migrations for common mistakes.
graft pack does the following:
- It builds everything.
- It records each route and its access level in
routes.json. - It works out which doors the graft uses.
- It hashes each file into
MANIFEST.json, and signs that list. - It writes
snippets-0.1.0.graft, and prints the Helm entry to install it.
graft pack fails if a route open to anyone is not listed in graft.json, or if the code uses a door without its capability.
Keep the private key secret. To let people trust your grafts, share the public key that graft keygen prints.
Licenses
Section titled “Licenses”@orchardlabs/graft-sdk is MIT licensed, so a graft that only imports it can use any license. @orchardlabs/graft-ui is licensed under AGPL-3.0-only. A graft that imports @orchardlabs/graft-ui must be released under a license compatible with AGPL-3.0-only, and the AGPL’s source-sharing terms apply to it. To use another license, build the graft’s UI with @orchardlabs/graft-sdk and your own components.
graft init adds @orchardlabs/graft-ui to the new graft, and the starter ui/src/Home.svelte imports it, so a scaffolded graft is under AGPL-3.0-only as it stands. To use another license, remove the dependency from package.json and the import from Home.svelte.
Next steps
Section titled “Next steps”- Review each field of the manifest
- Add API routes and reach Orchard through doors
- Add pages, navigation, tabs, and cards
- Add migrations and read Orchard’s tables
- Share your graft or list it in the Extension Marketplace
For an example, read the announcements graft. It has a server module, UI, migrations, and settings.
Related resources
Section titled “Related resources”- Graft UI slots - Every place in the dashboard a graft can add to.
- Graft API versions - Doors, their members, and the capability each needs.
- Troubleshooting grafts - Find out why a graft did not load.