This starterkit is meant to provide a good mix of best practices for working with Contentful in Next.js. It doesn't pretend to be the only way, but it is meant to address the main painpoints concerning data-fetching, component resolution, live previews, configuration management and App development. We believe a good starterkit is use-case based, but there is no good way to model all use-cases in same starter, so while we're starting as a marketing site, it may evolve later. In fact, it is modeled around Contentful's own Marketing Template content model, with a slight twist on the content part.
The starterkit's cornerstone is our data-fetching solution and it's typesafety. The goal is to have best-in-class Typescript-enabled, graphql-powered data fetching to eliminate guessing games in our components and provide full type definitions for free. The list of current features with descriptions can be found below.
- Next.js App Router usage for modern React Server Components approach - we think this is the way the industry will move to and it is a huge benefit for traditional websites to do data fetching only on the server and keep client bundle lean
- GraphQL + gql.tada plugin + Typescript for data fetching - we believe the best way to benefit from a GraphQL backend on the frontend is to use Typescript and be informed of what is available to you when you do data fetching, and gql.tada ensures you are not “lying to yourself” in your types by inferring them from the API.
- Cypress testing - we include a configured Cypress.io testing suite with ability to do both Component and E2E testing using Cucumber/BDD style syntax (optionally you can use traditional spec files too)
- Reference Component Architecture - we use Tailwind and shadcn/ui for the UI layer as a base, but more importantly the starter ships with reference component architecture that promotes UI component best practices. We focus on ability to reuse UI across projects, use of React Server Components for data-fetching and we demostrate how Contentful data can be integrated with a UI design system while preserving all Next.js features and Contentful features as part of the integration.
- Component Renderer - example of how to take a full tree of components and render them using a mapping of contentTypes to React components
- Draft Mode - preview mode for your application for Contentful Preview API usage
- Contentful Live Preview - Contentful live previews let you edit components side by side with a visual representation and Live Preview SDK also lets you annotate specific fields you are editing to get to the editor screen by just clicking “Edit” button on the frontend. We also integrated live updates, which will show result of content changes immediately as opposed to waiting for content to auto-save in Contentful.
- Contentful Content Source Maps - Optionally use Contentful Content Source Maps feature to get Live Preview SDK annotations without manually annotating your components, as well as get Vercel Content Link for Vercel customers.
- Turborepo - we use Turborepo for this project to showcase use of multiple packages for design system, CLI tooling, testing in addition to Next.js web app.
- This project is a template, feel free to either clone it (to preserve project history) or use click "Use this template" to create a repository with a single init commit. As soon as you have a repository, clone it locally
- Install dependencies with:
pnpm install
- Setup Contenful access To develop locally, you will want to connect to a Contentful instance that has the same data model as we use to develop, there are 3 ways to do that:
- You could get access to an existing space that follows Contentful Marketing Template content model, for example a colleague could share his space with you
- You could create your own space with https://www.contentful.com/starter-templates/marketing-website/. Keep in mind, new templates today can only be deployed on brand new Contentful accounts, so you might have to create a new account with a new email to do that, but this shouldn't be a problem, as it's free.
- You can start from scratch and use the contentful CLI and
apps/marketing/migrations/ctf-seed.jsonto import our demo content into your own contentful instance:pnpm --filter=marketing seed --environment-id=[ENVIRONMENT_ID] --space-id=[SPACE_ID]
You will want to get a CDA and CPA API keys by using this guide
- Configure environment
Create .env.local in apps/marketing directory of the repo with the following contents:
CONTENTFUL_SPACE=<space id>
CONTENTFUL_DELIVERY_API=<delivery api key>
CONTENTFUL_PREVIEW_API=<preview api key>
CONTENTFUL_ENVIRONMENT=master
CONTENTFUL_PREVIEW_SECRET=secret
# Enable or disable Content Source Maps, see https://www.contentful.com/developers/docs/tools/vercel/content-source-maps-with-vercel/
CONTENTFUL_USE_CONTENT_SOURCE_MAPS=true
- Run Next.js Dev Server
turbo dev --filter=marketingor run both Next.js and Storybook dev servers with:
turbo devOpen http://localhost:3000 with your browser to see the result.
- Component Architecture
- Components UI Folder
- Data-fetching guide
- Features guide
- Analytics guide
- Architecture Decision Records
- Next.js docs
The easiest way to deploy your Next.js app is to use the Vercel Platform from the creators of Next.js.
Customize the build command to be turbo run build and set the root directory to apps/marketing
Check out Next.js deployment documentation for more details.
While this starterkit is in active development, fixing some UI bugs or unfinished components may not be a priority.
This starterkit is meant to serve two purposes:
- Provide best practices for starting new projects with Contentful and Next.js
- Provide a demo site and a playground to test new features released in Next.js and Contenful
You are free to use the starterkit as a template to start new projects, but you can also pick and choose which reference implementations you like and copy them into your own project.
The demo site will evolve as we strive to demostrate more Next.js capabilities, but so will the Contentful part as Contentful adds more features (Contentful Studio, Taxonomy, etc)
Some features are going to be implemented just enough to demonstrate the concept in a demo, other features may be relying on particular infrastructure like on Vercel, it will be a balancing act.
Our commitment is to support majority of users and let them opt in, remove or modify certain functionality if they don't share the same infrastructure or feature set. We will provide documentation and guidance how to do that
This project is open-source under MIT license and accepts contributions, if you have any feedback, please create a discussion or an issue on Github.