optimizely-setup

Setup Optimizely CMS SDK

Guide the user through setting up the Optimizely CMS JavaScript SDK in their project.

Steps

1. Detect package manager - Check which package manager is used (npm, pnpm, yarn)
2. Install packages - Install @optimizely/cms-sdk and @optimizely/cms-cli
3. Create .env file - Create environment variables file with placeholders
4. Create config file - Create optimizely.config.mjs with basic configuration
5. Add .env to .gitignore - Ensure .env is not committed
6. Verify installation - Test the CLI connection

Implementation

1. Detect Package Manager

Check for lock files to determine the package manager:

if [ -f "pnpm-lock.yaml" ]; then
  echo "pnpm"
elif [ -f "yarn.lock" ]; then
  echo "yarn"
elif [ -f "package-lock.json" ]; then
  echo "npm"
else
  echo "npm"
fi

2. Install Packages

Based on the detected package manager, install the required packages:

• pnpm: pnpm add @optimizely/cms-sdk && pnpm add -D @optimizely/cms-cli
• yarn: yarn add @optimizely/cms-sdk && yarn add -D @optimizely/cms-cli
• npm: npm install @optimizely/cms-sdk && npm install -D @optimizely/cms-cli

3. Create .env File

Create .env file if it doesn't exist, with minimal required Optimizely environment variables:

# Base URL of your CMS instance
# Example: https://example.cms.optimizely.com/
OPTIMIZELY_CMS_URL=

# CLI client credentials for syncing manifest data
# Create in: CMS instance > Settings > API Keys > Create API key
OPTIMIZELY_CMS_CLIENT_ID=
OPTIMIZELY_CMS_CLIENT_SECRET=

# Content Graph authentication key
# Found in: CMS instance > Settings > API Keys
OPTIMIZELY_GRAPH_SINGLE_KEY=

Important: Remind the user to:

• Get credentials from their CMS instance: Settings → API Keys → Create API key
• Replace the placeholders with actual values
• Never commit .env to version control

Environment-specific configuration:

• Production: Use the variables above as-is. OPTIMIZELY_CMS_URL is required.
• Test (cmstest): Remove OPTIMIZELY_CMS_URL and add these instead:
  • OPTIMIZELY_CMS_API_URL=https://api.cmstest.optimizely.com
  • OPTIMIZELY_GRAPH_GATEWAY=https://staging.cg.optimizely.com/

4. Create Configuration File

First, ask the user if they want to set up property groups to organize their content type fields in the CMS editor.

Property groups help organize related content type properties together (e.g., SEO fields, metadata, layout settings). They're optional but useful for keeping the CMS editor organized.

If the user wants property groups, create optimizely.config.mjs with example groups:

import { buildConfig } from '@optimizely/cms-sdk';

export default buildConfig({
  components: ['./src/components/**/*.tsx'],
  propertyGroups: [
    {
      key: 'seo',
      displayName: 'SEO',
      sortOrder: 1,
    },
    {
      key: 'meta',
      displayName: 'Metadata',
      sortOrder: 2,
    },
  ],
});

If they don't need property groups, create the basic configuration:

import { buildConfig } from '@optimizely/cms-sdk';

export default buildConfig({
  components: ['./src/components/**/*.tsx'],
});

Adjust the components path based on the project structure (check if src/ exists, otherwise use appropriate path like ./components/**/*.tsx or ./app/components/**/*.tsx).

5. Add .env to .gitignore

Check if .gitignore exists and contains .env. If not, add it:

if ! grep -q "^\.env$" .gitignore 2>/dev/null; then
  echo ".env" >> .gitignore
fi

6. Verify Installation

Guide user to test the connection:

npx @optimizely/cms-cli login

If authentication fails, the user may be using a test environment or missing required variables. Guide them to:

1. Check if they need test environment (cmstest) configuration:
   • Add OPTIMIZELY_CMS_API_URL=https://api.cmstest.optimizely.com
   • Add OPTIMIZELY_GRAPH_GATEWAY=https://staging.cg.optimizely.com/
2. Verify all required variables are set (see "All Available Environment Variables" below)
3. Retry the login command

7. Add Missing Environment Variables (On Request)

When the user requests to "add all missing environment variables" or "add all possible variables", or when troubleshooting connection issues, reference this complete list of available environment variables:

# Base URL of your CMS instance
# Example: https://example.cms.optimizely.com/
OPTIMIZELY_CMS_URL=

# Content Graph endpoint
# Production (default): https://cg.optimizely.com/content/v2
# Test environment: https://staging.cg.optimizely.com/
OPTIMIZELY_GRAPH_GATEWAY=

# Content Graph authentication key
# Found in: CMS instance > Settings > API Keys
OPTIMIZELY_GRAPH_SINGLE_KEY=

# CLI client credentials for syncing manifest data
# Create in: CMS instance > Settings > API Keys > Create API key
OPTIMIZELY_CMS_CLIENT_ID=
OPTIMIZELY_CMS_CLIENT_SECRET=

# Feature Experimentation credentials (optional)
OPTIMIZELY_FX_SDK_KEY=
OPTIMIZELY_FX_ACCESS_TOKEN=

# Host of your application (optional)
APPLICATION_HOST=

# Base URL for CMS REST API endpoints
# Use instead of OPTIMIZELY_CMS_URL for test environments
# Test environment: https://api.cmstest.optimizely.com
OPTIMIZELY_CMS_API_URL=

# Required when CLI connects to local CMS with self-signed certificates
# NODE_TLS_REJECT_UNAUTHORIZED="0"

Variable purposes:

Required for all environments:

• OPTIMIZELY_CMS_CLIENT_ID/SECRET - Credentials for CLI to sync content type definitions
• OPTIMIZELY_GRAPH_SINGLE_KEY - Authentication for fetching content via Content Graph

Production environment:

• OPTIMIZELY_CMS_URL - Your CMS instance URL (e.g., https://example.cms.optimizely.com/)
• OPTIMIZELY_GRAPH_GATEWAY - Optional, defaults to https://cg.optimizely.com/content/v2

Test environment (cmstest):

• OPTIMIZELY_CMS_API_URL - Required instead of OPTIMIZELY_CMS_URL, set to https://api.cmstest.optimizely.com
• OPTIMIZELY_GRAPH_GATEWAY - Required, set to https://staging.cg.optimizely.com/

Optional variables:

• OPTIMIZELY_FX_SDK_KEY/ACCESS_TOKEN - Feature Experimentation integration
• APPLICATION_HOST - Your application's public URL
• NODE_TLS_REJECT_UNAUTHORIZED - Disable SSL validation for local development (security risk)

Next Steps

After setup, inform the user they can:

• Define content types using TypeScript in their components
• Sync types to CMS using npx @optimizely/cms-cli push
• Fetch content using the SDK's client utilities

References

• Installation Guide
• Setup Guide
• Modelling Guide