How I Deployed My Optimizely Content JS SDK Next.js App on Vercel (Hello Opti World)

📌 Scope: This post covers Optimizely CMS (SaaS) only, using the official content-js-sdk with Next.js 15 deployed to Vercel. This is a practitioner walkthrough — not official documentation.

⚠️ No official Vercel deployment guide exists for the content-js-sdk at the time of writing. This is what I figured out building my first app — Hello Opti World — from scratch.

I wanted to go from zero to a live Optimizely SaaS CMS site on Vercel using the official @optimizely/cms-sdk. The GitHub repo has great setup docs, but nothing on deploying to a hosted environment. This post fills that gap.

Step 1 — Your code on a Git repo

Vercel deploys from Git. Before anything else, push your Next.js app to GitHub, GitLab, or Bitbucket. For my Hello Opti World app I used GitHub.

Make sure your repo has an optimizely.config.mjs at the root — this is what the CLI uses to push content type definitions. Vercel doesn’t run the CLI for you; that’s a local step you do before deploying.

			
# Push your content type definitions to CMS before deploying
npx @optimizely/cms-cli@latest config push optimizely.config.mjs

Step 2 — Create a Vercel project

In Vercel, go to Add New → Project, connect your Git provider, and import your repo. Vercel auto-detects Next.js — no framework config needed.

Step 3 — Configure environment variables

This is the critical step. Before clicking Deploy, add all your Optimizely environment variables under Project Settings → Environment Variables. If you deploy without these the app will build but fail at runtime.

			
OPTIMIZELY_CMS_CLIENT_ID=XX
OPTIMIZELY_CMS_CLIENT_SECRET=XX
OPTIMIZELY_GRAPH_SINGLE_KEY=XX
OPTIMIZELY_GRAPH_GATEWAY=https://cg.optimizely.com/content/v2
OPTIMIZELY_GRAPH_HOST=https://hello-cjs-sdk.vercel.app

		

Set each variable for Production, Preview, and Development environments in Vercel. Don't leave them as Production-only or your preview deploys will break too.

Note : OPTIMIZELY_GRAPH_HOST is important when you have multi-site solution. SDK uses it to resolve your site from application configuration [See Step 4]

Step 4 — Configure your application

Make sure to configure your Vercel App URL/your URL as “Primary” for published version of your site.

Step 5 — Rebuild the Graph index

After pushing your content type definitions, always run a Graph Reindex before deploying. If the schema in Graph doesn’t match what your app queries, you’ll get empty results or runtime errors — not build errors, which makes it harder to catch.

CMS → Settings → Scheduled Jobs → Graph Delta Sync → Start

Run the reindex job before deploying to keep Graph schema in sync

Step 6 — Deploy (and redeploy)

Trigger a deploy — either by pushing a commit or clicking Redeploy in the Vercel dashboard. The first deploy after adding environment variables often needs a manual redeploy because Vercel caches the previous build without the new vars.

After adding or changing any environment variable, always do a fresh redeploy — don’t assume Vercel picks them up automatically from the last build.

Show successful build output in Vercel dashboard

Error I ran into

Framework Preset silently resets to “Other” after changing Root Directory

This one took a while to track down — thanks to my colleague Sophia for helping troubleshoot.

When you create a Vercel project, you set the Framework Preset to Next.js. But if you later update the Root Directory (needed when your app lives in a subdirectory of the repo), Vercel silently resets the Framework Preset back to “Other” — and that’s what caused the build error.

Fix: Go to Project Settings → General → Framework Preset → set it back to Next.js → trigger a new deployment.

Website is live on Vercel! 🎉

Once it’s live, confirm content is flowing end-to-end: publish something in the CMS, check the update on head/vercel app!