Introduction

Welcome to this course! This is a hands-on guide to building a production-ready Next.js application powered by Optimizely SaaS CMS using the official SDK and CLI.

This course is completely free. If you have any questions or feedback, feel free to reach out to me.

What You Will Learn

This course walks you through the complete integration pattern for Optimizely SaaS CMS with Next.js:

• How to use @optimizely/cms-sdk to define content types in code, fetch content, and render it dynamically
• How to use @optimizely/cms-cli to push your content type definitions to the CMS
• How to set up a clean project architecture that scales without becoming a maintenance burden
• How caching, ISR, and cache revalidation work together for a CMS-driven site
• How to support multiple languages with automatic locale detection
• How to set up preview mode for in-context editing in minutes

What Makes This Different

If you have worked with Optimizely SaaS CMS before, you might have used raw GraphQL queries, manually managed content type schemas in the CMS UI, and built your own block-rendering logic. This course shows a different approach — one where:

• Content types are defined in code using contentType() from the SDK and pushed to the CMS via CLI
• Rendering is fully automatic — OptimizelyComponent resolves the correct React component by content type without any manual switch statements
• The SDK is the source of truth for both TypeScript types and CMS schemas

This results in a codebase that is easier to maintain, easier to extend, and much less error-prone.

Course Repository

Repository: https://github.com/szymonuryga/Optimizely-CMS-Content-SDK-Next.js-16

This is the starter template we will explore throughout the course. Clone it, set up your environment variables, push the content types to your CMS instance, and you are ready to go.

Quickest Way to Get Started

The fastest way to explore this project is to clone the repository and use an AI assistant (Claude, GitHub Copilot, Cursor) to navigate and understand it. The repository includes a CLAUDE.md file at the root — a comprehensive knowledge base that documents the architecture, patterns, critical rules, and known gotchas of the project. AI tools read this file automatically and can give you detailed, accurate answers about how the project works, what each file does, and why decisions were made the way they were.

If you are stuck or want to understand something deeply, just ask your AI assistant — it has everything it needs to help.

Comparing This Approach to the Previous Course

This project uses the same React components as the Optimizely SaaS CMS Fundamentals course. The blocks, pages, and layouts look identical on the surface. The key difference is what sits underneath:

• In the fundamentals course, content is fetched with raw GraphQL queries, types are managed manually, and block rendering uses custom switch logic
• In this course, the SDK handles content types, GraphQL, and rendering — your job is just to define the schema and write the component

Having both courses side by side is intentional. You can compare the same component written both ways and decide which approach fits your project.

SDK Trade-offs: Speed vs. Control

The SDK speeds up development significantly — you skip a lot of boilerplate, get type safety for free, and rendering just works. But it is important to understand what you give up:

• No control over fetch configuration — the SDK manages GraphQL requests internally; you cannot add custom headers, timeouts, or retry logic at the fetch level
• Global error handling is harder — errors from the SDK's rendering pipeline are more difficult to intercept and handle uniformly
• Complex data sources become a burden — if your project combines Optimizely CMS content with another data source (e.g., a product catalog, a PIM, or a commerce platform), wiring them together through the SDK abstraction can create more friction than it removes

For a pure CMS site — landing pages, editorial content, structured marketing pages — the SDK is absolutely the right tool. For composable commerce or projects with heavy custom business logic, you may find that the SDK's abstractions get in the way more than they help. Know the trade-off before you commit.

Official Documentation

The official Optimizely documentation for @optimizely/cms-sdk is available here:

https://docs.developers.optimizely.com/content-management-system/v1.0.0-CMS-SaaS/docs/install-javascript-sdk

Use it alongside this course for the full picture — the docs cover the SDK API in detail, while this course focuses on how to structure a real project around it.

Who This Course Is For

This course is aimed at developers who:

• Are already familiar with Next.js App Router and React Server Components
• Have an Optimizely SaaS CMS instance or are planning to work with one
• Want to understand how to use the official SDK and CLI properly
• Want a clean, scalable project setup they can use as a base for real projects

Note: This is not a beginner Next.js course. If you are new to Next.js, I recommend checking out the fundamentals course first.

Let's get started!