The official JavaScript SDK and CLI from Optimizely CMS. Build headless applications with a code-first approach, full TypeScript support, intelligent code completion, and an intuitive developer experience.
A JavaScript/TypeScript library for fetching, rendering, and managing content from Optimizely CMS in your applications.
Key Capabilities:
- Type-safe content modeling with full TypeScript definitions
- First-class React and Next.js integration
- Real-time live preview and editing
- Advanced rich text rendering with extensibility
- Seamless digital asset management (DAM)
A command-line tool that syncs your TypeScript content type definitions to Optimizely CMS, enabling code-first content modeling.
Key Capabilities:
- Push TypeScript definitions to Optimizely CMS
- Simple, intuitive command-line interface
- Streamlined developer workflow
A collection of Agent Skills that teach AI coding agents how to work with Optimizely CMS.
Key Capabilities:
- Automated content type modeling
- React component generation
- Live preview setup and troubleshooting
- SDK configuration assistance
Compatible with: Claude Code, Cursor, GitHub Copilot, and others
Learn more: The skills live in the episerver/optimizely-cms-skills repository. See the Agent Skills guide for installation.
Framework Support: While the SDK is designed to be framework-agnostic, this version currently includes first-class support for React and Next.js. Support for additional frameworks is coming soon.
Before you begin, ensure you have the following:
| Requirement | Version | Notes |
|---|---|---|
| Node.js | 22+ | Download |
| Git | Latest | Version control |
| Package Manager | npm/pnpm/yarn | npm comes with Node.js |
| Optimizely CMS | Latest | Access to a CMS instance |
Get up and running in minutes:
# Install the SDK
npm install @optimizely/cms-sdk
# Install the CLI (for type syncing)
npm install -D @optimizely/cms-cliFor a complete walkthrough from scratch, see the Documentation section below.
Reference implementations demonstrating best practices:
Production-ready Next.js site showcasing advanced patterns and features.
- Live Demo: https://nextjs-sample-js-sdk.vercel.app/
- Source:
templates/stride/ - Features: Experiences (Composition), Live Preview, Display Templates
Starter template with essential features and clean architecture.
- Source:
templates/alloy/ - Features: Content Types, Contracts, Experiences (Composition), Display Templates, DAM assets, Live Preview
Both templates follow SDK best practices and serve as learning resources.
The SDK includes built-in OpenTelemetry instrumentation for production observability. All major operations are automatically traced, including GraphQL queries, content fetching, and component resolution.
// Initialize OpenTelemetry SDK first
import { NodeSDK } from '@opentelemetry/sdk-node';
const sdk = new NodeSDK({ /* your config */ });
sdk.start();
// Then use the Optimizely SDK - all operations automatically instrumented
import { config, getClient } from '@optimizely/cms-sdk';
config({ apiKey: 'your-key' });
const client = getClient();
await client.getContentByPath('/'); // Automatically creates spansWhat gets instrumented:
- Content retrieval (
getContentByPath,getContent,getPreviewContent) - GraphQL query and fragment generation
- HTTP requests to Optimizely Graph
- Component resolution and rendering (React)
Learn more: See the complete Observability guide for setup, span details, and production configuration.
Reference implementation: See samples/nextjs-template/src/instrumentation.ts for a working example with Next.js.
Start at the documentation home, or jump straight in:
- Quick start - Scaffold a working site from a template
- Tutorial - Build a site step by step: install, connect, model, fetch, render and preview
- Guides - Content types, experiences, display templates, rich text, forms, authentication and more
- Reference -
config(),GraphClient, React components, CLI commands and every option
We're here to help you succeed with Optimizely CMS:
- Community Slack - Join the Optimizely Community Slack for real-time discussions
- GitHub Issues - Report bugs or request features on GitHub
- Documentation - Browse our documentation and guides.
The easiest way to contribute is to join in with the discussions on GitHub issues or create new issues with questions, suggestions or any other feedback. If you want to contribute code or documentation, you are more than welcome to create pull-requests, but make sure that you read the contribution page first.
This project is licensed under the Apache License 2.0.
Built by the Optimizely CMS Team