In this lesson, you'll build a real Next.js application that fetches and displays products from your Webiny Headless CMS.

What you'll build:

The project scaffold for the Learn Webiny Next.js app: environment setup, an API key, TypeScript types, and an initialized SDK instance ready to use in the following lessons.

Prerequisites:

• Completed Lessons 1-4 (content models and entries)
• At least 2-3 published products in your Webiny CMS
• Node.js 20.9+ and npm/yarn installed
• Basic understanding of React and Next.js

Introduction

So far, you've learned how to create content models and add entries to Webiny. Now it's time to connect an actual application to your CMS.

In this lesson, we'll set up a Next.js project and wire it up to Webiny using the Webiny SDK (@webiny/sdk) — a TypeScript library that gives you a clean, type-safe interface to the Webiny APIs without writing raw GraphQL.

This lesson focuses purely on project setup: cloning the starter, creating an API key, configuring credentials, and initializing the SDK. The next two lessons will put the SDK to work — reading products and writing contact form submissions.

This lesson establishes the foundation for the next lessons where we'll add a contact form, implement lifecycle events, and more!

Project Setup

First, let's set up the Next.js project.

Step 1: Clone the Starter Repository

For this tutorial, we'll use a basic Next.js starter repository that's been set up with TypeScript and Tailwind CSS:

Clone the repository and install dependencies:

Step 2: Explore the Project Structure

The starter project has a basic Next.js 16 setup with TypeScript and Tailwind CSS:

Step 3: Run the Development Server

Start the dev server to confirm everything works:

Open http://localhost:3000 in your browser. You should see a simple page with "Our Products" heading - that's your starting point!

Finding Your API Endpoint

Before we can connect to Webiny, we need to find the API endpoint URL.

Open a terminal in your Webiny project directory (not the Next.js app) and run:

You'll see output similar to this:

Click to enlarge

Look for the Headless CMS - Read API URL in the output. It will look something like:

We need the base URL part (the domain). In this example, it would be:

https://d1ud9w3i9i7d77.cloudfront.net

Copy this URL - you'll need it in the next step.

Headless CMS Permissions and GraphQL APIs

Before creating an API key, it's worth understanding what permissions you're actually granting. Webiny's Headless CMS exposes three separate GraphQL APIs, each with a distinct purpose:

When you create an API key, you select which of these APIs the key can access. The principle of least privilege applies: only grant what you actually need.

• Reading data (e.g. product listings) → enable Read only
• Previewing drafts → enable Read + Preview
• Writing data (e.g. contact form submissions) → enable Manage (Read is still needed for reading)

In this lesson we'll start with Read only, since we're just displaying published products. In the Writing Data lesson we'll expand the key to also include Manage.

Creating an API Key

Now let's create an API key that allows the Next.js app to access your Webiny CMS.

Step 1: Navigate to API Keys

1. Open the Webiny Admin in your browser
2. Click Settings in the left sidebar
3. Click API Keys

Step 2: Create a New API Key

Click the New API Key button in the top right.

Step 3: Configure the API Key

Fill in the following details:

1. Name: Next.js App
2. Description: API access for Next.js application
3. Permissions: Click on Headless CMS to expand the section

Click to enlarge

Step 4: Set Permissions

Configure the permissions as follows:

1. Access Level: Select Custom access
2. GraphQL API Types:
   • ✅ Read (checked)
   • ❌ Preview (unchecked)
   • ❌ Manage (unchecked)

Click to enlarge

Step 5: Save and Copy the Token

1. Click Save API Key
2. The form will be saved and your API Token will be displayed in the Token field
3. Copy the token by clicking the copy icon - you'll need it in the next step!

Click to enlarge

Setting Up Environment Variables

Now let's store the API URL and token securely.

Step 1: Create .env.local

In your Next.js project (not the Webiny project), create a new file called .env.local in the root directory:

Replace:

• your-api-token-here with the token you copied in the previous step
• https://your-url.cloudfront.net with your actual API endpoint URL

Step 2: Restart the Dev Server

Environment variables are only loaded when the dev server starts, so you need to restart it:

1. Stop the dev server (Ctrl+C or Cmd+C)
2. Start it again: npm run dev

Creating the API Client

Now let's create a reusable API client for communicating with Webiny. We'll use the Webiny SDK which makes interacting with the CMS much simpler than writing raw fetch requests.

Create a new file lib/webiny.ts:

Let's break down what this code does:

1. Environment Variables: Loads the API endpoint, token, and tenant.
2. SDK Initialization: We initialize Sdk with the token, endpoint, and tenant.
3. Exports: We export both the SDK instance and the CmsEntryData type for use throughout the application.

Summary

In this lesson, you set up the Next.js project and connected it to Webiny:

• ✅ Cloned the starter repository and installed dependencies including @webiny/sdk
• ✅ Found your Webiny API endpoint using yarn webiny info
• ✅ Created an API key in Webiny Admin with Read permissions
• ✅ Stored credentials securely in .env.local
• ✅ Initialized the Webiny SDK in lib/webiny.ts

What's Next?

In the next lesson, we'll use the SDK to fetch products from Webiny and display them on the page using Static Site Generation.

---

Next lesson: Reading Data - Fetch and display products from Webiny using the SDK and SSG.