Gatsby Starter Contentful Homepage

Gatsby Starter Contentful Homepage is a JavaScript starter kit from the Gatsby team that scaffolds a content-driven homepage with Gatsby as the front-end and Contentful as the headless CMS.

What is Gatsby Starter Contentful Homepage?

This starter's core function is to build a homepage whose content is managed in Contentful and rendered by Gatsby. As input it takes a Contentful Space ID, a Content Management API key, and a Content Delivery API key; as output it produces a Gatsby site with a pre-built homepage composed of modular sections. The project is created with npx gatsby new from the gatsbyjs/gatsby-starter-contentful-homepage repository, and it runs on the Gatsby framework. Gatsby, the company behind the framework, maintains this starter and its companion TypeScript version.

Key Features

• Gatsby and Contentful integration — The starter includes a setup script that populates a Contentful space with a full content model and demo content, so the homepage is editable immediately.
• Modular homepage sections — Out of the box the homepage includes hero, feature list, logo list, benefit list, testimonial list, stat list, call-to-action, and product list sections, each implemented as a component in src/components and exported from sections.js.
• Vanilla Extract styling — Colors are defined in src/colors.css.ts and imported into theme.css.ts to generate CSS custom properties; individual UI components import these styles from ui.css.ts.
• Customizable branding — The logo lives in src/components/brand-logo.js as an inline SVG, and the README explains how to replace it with your own SVG or a StaticImage from gatsby-plugin-image.
• Extensible content model — gatsby-node.js defines abstract interfaces (for example, HomepageBlock) so you can add new section types such as a "Homepage Banner" by updating the content model, creating a React component, and registering it in sections.js.
• Gatsby Cloud deployment — The repository supports one-click deployment to Gatsby Cloud through the gatsby-provision convention, which can automatically provision Contentful content during the Deploy Now flow.

Who is it for?

• Gatsby developers — They can use this starter to skip initial setup and focus on customizing a content-managed homepage.
• Agencies and freelancers — They can white-label the starter by editing colors.css.ts and brand-logo.js to match a client's visual identity, then hand off content editing to the client in Contentful.
• Teams adopting a headless CMS — The starter demonstrates a clean separation between content (Contentful) and presentation (Gatsby), making it a working reference for architecting similar sites.

What can you do with Gatsby Starter Contentful Homepage?

• Rebrand the site — Change the color palette in colors.css.ts, replace the inline SVG logo in brand-logo.js, and adjust headings, buttons, and shared styles in src/components/ui.js and ui.css.ts.
• Create a new homepage section — Follow the README tutorial to add a "Homepage Banner": create a content type in Contentful, define a matching interface in gatsby-node.js, build a Banner component, export it from sections.js, and append its GraphQL fragment to the homepage query.
• Deploy with content provisioning — Push the site to GitHub, GitLab, or Bitbucket, connect the repo to Gatsby Cloud, add Contentful environment variables, then let Gatsby Cloud run gatsby-provision to populate the space and build the site.
• Set up Gatsby Cloud Preview — Use the included documentation link for installing Content Sync for Contentful to enable previews of unpublished content.

How does the starter work?

After creating the site with npx gatsby new, you run yarn setup at the project root. That script populates your Contentful space with the required content model and demo content. Then yarn start launches the development server at localhost:8000. When you deploy to Gatsby Cloud, the gatsby-provision script can run automatically during the import flow.

Pros and cons

• Pros — Open-source and free to use; includes an automated content provisioning script; uses a modular component architecture that makes section customization straightforward; provides a separate TypeScript version for type-safe development.
• Cons — You must supply your own Contentful space and API keys; the default dataset omits About-page content because Contentful's free plan limits the number of content types (the README explains how to include it if you have a paid space).

FAQ

Does this starter require a Contentful account?

Yes. You need a Contentful space, plus a Space ID, a Content Management API key (also called a Personal Access Token), and a Content Delivery API key. The setup script uses these credentials to populate the space with the starter's content model and demo content.

How do I change the site's colors?

Edit the color tokens in src/colors.css.ts. The file exports a JavaScript object that theme.css.ts uses to generate CSS custom properties, which are then consumed by the UI components in src/components/ui.css.ts.

Why is the About page content missing?

When this starter was first released, Contentful adjusted the number of content types allowed in a free space. As a result, the default data set omits About-page content types. If you have a paid Contentful space, rename scripts/data-with-about-page.json to /scripts/data.json before running yarn gatsby-provision.

Is there a TypeScript version?

Yes. This repository is the JavaScript version, and the Gatsby team maintains a separate TypeScript version on GitHub at gatsbyjs/gatsby-starter-contentful-homepage-ts.

How do I deploy to Gatsby Cloud?

Push the site to GitHub, GitLab, or Bitbucket, then in Gatsby Cloud click "Add a site" and choose "Import from a Git repository." Add the environment variables from your .env.production file, click "Build site," and the build will start. Gatsby Cloud can also run gatsby-provision to set up Contentful content during deployment.