Decoupled Kit JS

Pantheon Systems Decoupled Kits is a monorepo of JavaScript starter kits, reusable npm packages, and SDKs maintained by Pantheon for building decoupled Drupal and WordPress sites with Next.js and Gatsby.

What is Pantheon Decoupled Kits?

Pantheon Decoupled Kits is a monorepo organized by pnpm workspaces, containing two main workspaces: starters (starter kits like gatsby-wordpress-starter) and packages (publishable npm libraries such as nextjs-kit), plus a configs workspace and a web workspace for documentation. It serves as Pantheon's central codebase for headless CMS front-end projects. The repo takes starter kit source code and packages as input, and produces standalone starter repositories and published npm packages through its release automation.

Key Features

• pnpm workspace structure — The monorepo is split into starters, packages, configs, and web workspaces; each starter directory is mirrored to its own standalone repo at release time.
• Gatsby starter — Includes gatsby-wordpress-starter, runnable with pnpm --filter gatsby-wordpress-starter develop.
• Reusable npm packages — The packages workspace contains libraries like nextjs-kit that are published to npm and consumed by the public and by the starter kits.
• Changeset-based versioning — Run pnpm changeset to generate Markdown changelog files in the .changeset directory; CI creates versions automatically.
• Canary release workflow — Every push to the canary branch triggers a GitHub Action that opens a PR and, on merge, publishes changed packages to the canary tag on GitHub and npm.
• Automated testing and CI — GitHub Actions workflows run unit tests, headless regression tests, canary release checks, and starter split/release processes.
• Targeted execution with filters — Use pnpm --filter to run commands in a specific project, e.g. pnpm --filter './starters/**' lint to lint all starters.
• Documentation site generation — The web workspace has its own docs, built with pnpm generate-docs and served with pnpm start:docs.

Who is it for?

• Developers starting decoupled projects — use the starter kits to get a working Next.js or Gatsby front-end connected to Drupal or WordPress.
• Pantheon customers on WebOps — use these kits and packages to accelerate headless site builds within Pantheon's workflow.
• Open-source contributors — can fork the repo, follow the setup steps (pnpm install, pnpm husky install), and submit changes via bug report or feature request templates.

What can you do with Pantheon Decoupled Kits?

• Spin up a Gatsby WordPress site: run pnpm --filter gatsby-wordpress-starter develop to launch the Gatsby starter locally against a WordPress backend.
• Incorporate reusable packages: import nextjs-kit and other published packages into your own decoupled front-end applications.
• Develop a new starter or package: add code in the relevant workspace, generate a changeset with pnpm changeset, and let CI handle canary releases and splitting.
• Build project documentation: run pnpm generate-docs to compile the docs from the web workspace.

How does it work?

To set up the monorepo: install Node.js LTS, npm 10.x, and pnpm 8.x; fork and clone the GitHub repo; run pnpm install to install dependencies and trigger a postinstall build of packages; then run pnpm husky install to activate pre-commit hooks. From there, you can use pnpm test, pnpm build:pkgs, or filtered commands to develop and test projects.

FAQ

What are the prerequisites for using Pantheon Decoupled Kits?

You need Node.js LTS (nvm is recommended), npm version 10.x, and pnpm version 8.x. The README suggests installing pnpm globally with npm install -g pnpm@8.

How do I run the Gatsby starter?

From the repository root, use the filter flag: pnpm --filter gatsby-wordpress-starter develop. This starts the Gatsby starter without needing to cd into the project directory.

How are releases published?

Each push to the canary branch runs the canary-release.yml workflow, which opens a PR back to the repo. On merge, any package with a changeset is released to the canary tag on GitHub and npm.

How can I report a bug or request a feature?

The README links to a bug report template and a feature request template under GitHub issues, so you can file issues against the monorepo directly.