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: See the packages/optimizely-cms-skills/ package
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.
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.
A step-by-step guides to build your headless application:
| Step | Guide | Description |
|---|---|---|
| 1 | Installation | Set up your development environment |
| 2 | Setup | Configure the SDK and CLI |
| 3 | Modelling | Define your content types with TypeScript |
| 4 | Create Content | Add content in Optimizely CMS |
| 5 | Fetching Content | Query and retrieve content in your app |
| 6 | Rendering (React) | Display content in React components |
| 7 | Live Preview | Enable real-time content editing |
| 8 | Experience | Work with experiences and variations |
| 9 | Display Settings | Configure content display options |
| 10 | RichText Component (React) | Render rich text content |
| 11 | DAM Assets | Manage digital assets |
| 12 | Client Utils | Utility functions and helpers |
| 13 | Agent Skills | AI-powered development |
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