Gatsby Craftcms Barebones

Gatsby Craftcms Barebones is a boilerplate project that pairs Gatsby with a headless Craft CMS backend, exposing content through the CraftQL GraphQL plugin.

What is Gatsby Craftcms Barebones?

Gatsby Craftcms Barebones is a starter template for building a headless CMS site with Gatsby as the front end and Craft CMS as the backend. It walks through installing a new Gatsby project, adding Craft CMS via Composer into a craft subdirectory, setting up MySQL, linking Laravel Valet, creating a Posts section, and installing the CraftQL plugin to serve content over GraphQL. The final setup lets developers query Craft entries from Gatsby using gatsby-source-graphql.

Key Features

• Craft CMS backend — Content is managed in Craft CMS, with a Posts section and a plain-text field named "post content" configured in the admin panel.
• CraftQL GraphQL API — Installs the CraftQL plugin (version 1.0.0) via Composer to expose an endpoint at craft.test/api.
• Gatsby-source-graphql integration — Adds gatsby-source-graphql to gatsby-config.js, with a field name of craft and a type name of Craft.
• Environment variable handling — Requires dotenv to load the CraftQL API token from a .env.development file created at the project root.
• Sample Twig template — Includes an index.twig file that loops through all entries in the Posts section and displays each title and post content.
• Local development workflow — Provides explicit commands for using Laravel Valet (valet start and valet link) and initializing Craft through the browser at craft.test/index.php?p=admin/install.

Who is it for?

• Developers exploring headless CMS architecture — Use this starter to learn the connection between Gatsby and Craft CMS through GraphQL in a local environment.
• Agencies building blog-style websites — Set up a content-managed blog where editors create posts in Craft CMS and Gatsby renders them as static pages.
• Teams evaluating Craft CMS as a headless backend — Get a minimal working example with CraftQL and GraphQL queries instead of building the integration from scratch.

What can you do with it?

• Create and manage content: Add a Posts section, define a post content field, and write entries from the Craft admin dashboard.
• Query content with GraphQL: Run a query against craft.test/api to fetch entry titles and post content, verifiable with GraphiQL or curl.
• Render content in Gatsby: Use the data returned from the CraftQL endpoint to display posts, with a sample query provided for all entries.

How does it work?

The setup follows a specific sequence: create a Gatsby project with gatsby new, install Craft CMS with composer create-project craftcms/craft, start a MySQL database and configure the .env file, link the directory with Valet, install Craft through the browser, create a Posts section and entries, enable the CraftQL plugin and generate a token, then configure gatsby-source-graphql with that token in the environment file. The result is a Gatsby site that can fetch Craft content through GraphQL.

FAQ

What prerequisites are needed?

You need PHP, Composer, Laravel Valet, MySQL, and the Gatsby CLI installed globally. The README directs users to the Valet documentation and the MySQL download page for setup.

Does this starter include a pre-built Gatsby theme?

No, it is a barebones configuration. The Gatsby project is created with gatsby new, and the starter only adds the source plugin and environment setup. The included Twig template is a minimal display example, not a full theme.

Is this starter production-ready?

It is designed for local development and integration testing. The steps focus on getting a working connection between Craft CMS and Gatsby, not on deployment, styling, or performance optimization.

How is the CraftQL token stored?

The token is generated in the CraftQL plugin settings and placed in a .env.development file at the project root. The gatsby-config.js file reads it with dotenv and sends it as an Authorization header with a bearer prefix.