optimizely-cms-skills

---

Overview

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.

What's Included

🚀 SDK - Content Delivery & Management

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)

⚙️ CLI - Type Definition Sync

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

🤖 Agent Skills - AI-Powered Development

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.

Prerequisites

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

Quick Start

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-cli

For a complete walkthrough from scratch, see the Documentation section below.

Observability

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 spans

What 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.

Documentation

A step-by-step guides to build your headless application: