Framework-Specific Starter Kits Made from Framework-Agnostic Packages

Pantheon customers using Front-End Sites in the Pantheon dashboard have likely noticed a new selection of starter kits when creating a site. Most recently, we added a WordPress + Next.js combination.

These starters are one of the more visible outputs of an open source initiative at Pantheon that we’re calling Decoupled Kit. Decoupled Kit is the open source connective tissue between front-end frameworks and back-end CMS instances that unlocks the value of our new Front-End Sites product. As the lead engineer for Decoupled Kit (and as the former agency developer who really could have used Decoupled Kit a few years ago), I wanted to share some detail on the motivation behind this project, and how it could be used by a variety of teams building sites using decoupled architectures.

The WordPress and Drupal communities have clear best practices to expose back-end data via APIs. Yet, there is unsurprisingly a wide variety of possible approaches to consume this data in front-end frameworks. As a result, we see a number of common problems in decoupled projects being solved over and over in different ways. Things as simple as fetching data from an API can vary from site to site.

Do you really need to reinvent fetching WordPress posts because you decide to switch from Gatsby to Next.js or vice versa?

Pantheon's Decoupled Kit can help.

Decoupled Kit is a collection of utilities for building a decoupled front-end that sources data from a CMS back-end. Conceptually, a ‘“Kit” is a combination of a compatible CMS back end and JavaScript front end. For example, we have kits with WordPress + Gatsby, WordPress + Next.js, and Drupal +Next.js. 

At a slightly lower level, Decoupled Kit is a series of CMS starter projects, front-end starter kits, and developer documentation. Let’s take a closer look at each of these focus areas.

CMS Starter Projects

Our CMS starter projects are Pantheon-maintained upstreams that install and configure useful dependencies for decoupled projects. For instance, our Decoupled WordPress upstream pulls in the increasingly ubiquitous WPGraphQL plugin. Our Decoupled Drupal upstream pulls in the Decoupled Router contrib module in order to make it easier to resolve path aliases and redirects.

Both upstreams also provide sample content to fill out our example front-end integrations. These starter projects aren’t focused on an individual JavaScript framework, instead they are intended to work well with multiple frameworks (including ones that don’t exist yet!).

See these starter projects on GitHub:

• Decoupled Drupal Composer Managed
• Decoupled WordPress Composer Managed

While these Composer projects can be used for a simplified setup, they primarily assemble install profiles, modules, and plugins that can be installed separately. Also of note here is the Decoupled Preview module for Drupal, which allows you to preview content on your front-end site. A comparable WordPress plugin is in active development.

Front-End Starter Kits

Our front-end starter kits contain sample content integrations, and require nearly zero configuration when used with a compatible CMS starter project. Where possible, the starter kits take advantage of common components and packages which allows for comparable functionality and look and feel regardless of the combination of back-end and front-end projects selected.

See these starter kits on GitHub:

• Decoupled Kit Next Drupal Starter
• Decoupled Kit Next WordPress Starter
• Decoupled Kit Gatsby WordPress Starter

We expect to expand the list of starter kits in the future based on community interest and the never-ending rise and fall of JavaScript frameworks.

For now, we see clear and growing interest in Next.js. So check out John Richards, our manager of developer advocacy walking through WordPress with Next.js over on our YouTube channel.

Separately Installable Packages

While we think most teams that get rolling with decoupled architectures should start with the starter kits, more experienced teams might want to work with the individual pieces from the kit. That's why we are also publishing on npm the important component parts of these kits as their own packages.

A key part of our approach here is that we’re focusing on building utilities that are framework-agnostic by default, and only creating framework-specific utilities when necessary. The hope is that this approach will make it easier to adapt alongside the ever-evolving JavaScript ecosystem, and also make these packages useful to a wider variety of projects.

Check out these packages on npm:

• WordPress Kit – Framework-agnostic utilities to source data from WordPress through GraphQL. It also includes Tailwind plugins that improve Block Editor support.
• Drupal Kit – Framework-agnostic utilities to source data from Drupal JSON:API ecosystem.
• Next.js Kit – Next.js specific utilities and components used by both the Drupal and WordPress starter kits.

An ongoing area of focus in the WordPress Kit and Drupal Kit packages is managing caching across the entire stack. Stay tuned for more details as we further leverage CMS cache metadata across CDN and front-end framework layers.

Developer Documentation

Complementing Pantheon’s platform-specific Front-End Sites documentation, we’re also maintaining in-depth developer documentation specific to these open source projects. The docs currently contain sections related to each of the back-end and front-end starter projects, guides to making customizations, common troubleshooting and detailed API documentation for our packages.

We expect this documentation to grow over time, both as additional tools are added to Decoupled Kit and also as a home for general examples and best practices for building decoupled sites.

Published Documentation:

• Decoupled Kit Developer Docs

Possible Uses

Given that these projects can be used in a variety of different contexts, the best way for you to take advantage of them may vary depending on your project. They could be:

• A quick and easy way to evaluate Front-End Sites on Pantheon, providing a streamlined first-run experience when creating a new project from the Pantheon Dashboard.
• A reference implementation.
• A starting point for your build.
• A menu of à la carte utilities to use as part of your project as you see fit.

That last item is worth lingering on a bit. We hope these tools can help support a great experience on Pantheon using the starter kits, but we’re also hopeful that they prove useful in a variety of site builds. Have a need for the WordPress block editor utility classes provided by our WordPress Kit package? `import '@pantheon-systems/nextjs-kit/style.css';` into your existing project and enjoy.

We Want Your Feedback

Given the wide potential scope of Decoupled Kit, community feedback is extremely important. There are many possible frameworks to support and use cases to improve, but we want to make sure that we’re focusing on things that will actually prove useful to our users and the overall decoupled CMS ecosystem. 

We monitor issues in all of the projects listed throughout this article, but the best place to share feedback or raise an issue is in the decoupled-kit-js monorepo on GitHub, since it contains the largest cross-section of our projects. For general discussion, we encourage you to join the #front-end-frameworks channel in the Pantheon Community Slack or jump into a discussion on GitHub. Finally, if you prefer a real-time discussion over Zoom, Decoupled Architecture Office Hours (Tuesdays at 10:30am ET / 3:30pm UK) are for you.

We’re excited about the future of Decoupled Kit and can’t wait to hear how you’re using it to build Front-End Sites on Pantheon. If you don't yet have access to Front-End Sites, tell us about your interest here.