Next.js • Tailwind • Contentful Easy Starter

Why

After so much time working with Contentful and Next, I never found a single consistent way of starting a project, and all starters that tried have their own caveats, some are too basic without touching the real problems like handling GraphQL query complexity limits or are too strict. I'm not saying this starter is better as there are many ways to accomplish the same thing when building with these technologies. Anyway, it was a lot of fun building it, exploring the nice features of React SSR inside Next.js, and playing with Contentful content modeling capabilities.

The tech stack

• ⚡️Next.js 15 with App router

• ⚛️ React 19

• ✨ TypeScript

• 💨 TailwindCSS + 🌻 DaisyUI

• 🌞 Contentful

• 🗄️ Turso DB

• 👷Code on Github under the MIT License.

• 🌩️ Hosted on Vercel but be free to use a compatible hosting solution that you prefer

Key Decisions

• Not just another starter, it's optioned in the way content models are shaped and how they are consumed in the FE.

• Keep it simple but still powerful - like mentioned initially I wanted something that can be used in the real world and not another basic example.

• Aware of limitations of using Contentful free tier - Limitations on the number of content models, locales, records, etc... are naturally applied. Being a hobby project and targetting personal websites I think the free tier makes all the sense, but bear in mind that if you want to use this for something more advanced I strongly recommend going with a paid tier.

  • Everything works with 20 content models (the limit on the free tier is 25).

  • Making content models suited for different cases (e.g. Hero can be used for 3 completely different hero components in the FE by using variant fields).

  • Implementation is aware of potential limits with GraphQL and deals accordingly with that.

• Using DaisyUI for the sake of simplicity, but with the ability to change/extend the themes.

• Flexibility in mind

• Performance, on my tests the main pages I got a 99 on the homepage and 100 on the about page 🎊

Main Features

• Flexible and composable content models

• SEO ready with Metadata being generated based on specific SEO fields but with fallbacks in place

• Generation of GraphQL (schema, and types), in sync with the content types via graphql-codegen.

• Typescript

• Tailwind CSS via DaisyUI

• Nextjs SSR components

• Contentful Live preview supporting inspector mode

• Easy installation

Requirements

• Access to a Contentful space (you can register for free here)

• Optionally Turso DB is required for newsletter signups and article views counter.

• An environment where you can run Node 18+

• pnpm installed

Installation

1. Clone the repo

2. Install with pnpm

1
2
3
4
5
6
7
8
9
10
11
git clone git@github.com:pauloamgomes/netcs.git
cd netcs
pnpm install

cp .env.example .env

# Grab your Contentful Space ID, Environment ID and Access Token and update the .env file
# CONTENTFUL_SPACE_ID=<your-space-id>
# CONTENTFUL_ENVIRONMENT_ID=<your-environment-id>
# CONTENTFUL_ACCESS_TOKEN=<your-access-token>
# CONTENTFUL_MANAGEMENT_TOKEN=<your-mgmt-token>

If you want to have article view counts and newsletter registration (optional)

1. Create a Turso database

2. Get an Auth token

3. Place the Turso database url and auth token in your .env file

4. Run the migration command and push the migrations

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# install and check installed version
brew install tursodatabase/tap/turso
turso --version

# signup/auth
turso auth signup # signup with github

# db creation
turso db create netcs-db # choose your own db name

# get db endpoint and auth token
turso db show netcs-db
db tokens create netcs-db 

# run and push the migrations
pnpm run db:generate
pnpm run db:push

# check on the Turso dashboard for your changes or run the editor locally
pnpm run db:studio

Import example Data into Contentful

In order to be able to start the local server Contentful needs to have all content models created along with the example data, you can easily do it using the command contentful:seed

pnpm run contentful:import

The above command will import all example data you can see in this example website in your space.

Start Local server

If you did all the previous steps without errors and you feel courageous you can try to start the local server by running:

1
2
3
4
5
6
7
8
9
10
11
12
13
pnpm run dev

# and you should receive

> graphql-codegen --config codegen.ts

✔ Parse Configuration
✔ Generate outputs
   ▲ Next.js 14.0.2
   - Local:        http://localhost:3000
   - Environments: .env

 ✓ Ready in 1113ms

And voila, it works! 🎉

Configuring Live Preview

In order to use Contentful Live preview it's only required to set up a new Content Preview in Contentful:

If you are testing locally you can use a tool like ngrok to publicly expose your local server.

Building Blocks

The project includes also a few components that are the foundation for assembling the pages or the article details page.

Accordions

Cards

Cards are used in several places and defined in the Card component, they can be easily reused. Here is an example of using the card for rendering an article:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
<Card as="li">
  <Card.Image
    url={image.url}
    alt={image.title}
  />
  <Card.Title href={getPageUrl(article)}>
    {article.title}
  </Card.Title>
  <Card.SubTitle className="text-xs justify-between">
    <span>{formatDate(article.publishedDate)}</span>
    <CategoryBadge
      category={
        article.categoriesCollection?.items?.[0] as Category
      }
      className="text-xs"
    />
  </Card.SubTitle>
  <Card.Description height="sm">{article.summary}</Card.Description>
  <Card.Cta>view more</Card.Cta>
</Card>

Code Block

The code block is useful to display code snippets, it depends on the Contentful Code Editor Field App and React Syntax Highlighter.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// index.tsx

import React from 'react';
import Link from 'next/link';

const HomePage: React.FC = () => {
  return (
    <div>
      <h1>Welcome to Next.js!</h1>
      <nav>
        {/* Using Link for client-side navigation */}
        <Link href="/about">
          <a>About Page</a>
        </Link>
        <br />
        <Link href="/services">
          <a>Services Page</a>
        </Link>
      </nav>
    </div>
  );
};

export default HomePage;

Media

The Media block allows embedding videos from a video provider like Youtube or Vimeo or directly uploading in Contentful as an asset file.

Information Message

Notifications

It's possible to configure global notifications that will be displayed as toast elements in the bottom right side of the screen and persist on the local storage.