Nuxt Studio

Nuxt Studio Setup and Deployment

Overview

Nuxt Studio is a free, open-source visual content editor for Nuxt Content websites that enables content editing directly in production. It provides multiple editor types (Monaco code editor, TipTap visual WYSIWYG editor, Form-based editor), OAuth authentication (GitHub/GitLab/Google), and Git-based content management with commit integration.

Primary use case: Add visual CMS capabilities to existing Nuxt Content websites, typically deployed to a subdomain like studio.domain.com or cms.domain.com.

When to Use This Skill

Use this skill when users need to:

• Set up Nuxt Studio for the first time on a Nuxt Content website
• Configure OAuth authentication for Studio access
• Deploy Studio to Cloudflare Pages or Workers with custom subdomain
• Troubleshoot Studio authentication, build, or deployment issues
• Configure editor types or customize Studio behavior
• Integrate Studio with existing Nuxt v3/v4 applications

Prerequisites Check

Before proceeding with Studio setup, verify these requirements:

1. Nuxt Version: ≥3.x (Studio requires Nuxt 3)
2. @nuxt/content Module: ≥2.x (required dependency)
3. Node.js: ≥20.x recommended
4. Cloudflare Account: Required for Cloudflare deployment (optional for other platforms)

Check Nuxt Content installation:

# Verify @nuxt/content is installed
grep "@nuxt/content" package.json

# Check nuxt.config.ts for content module
grep "modules.*content" nuxt.config.ts

If Nuxt Content is not installed, install it first:

npx nuxi module add content

Installation

1. Install Nuxt Studio Module

Install the latest beta version (v1.0.0-beta.3 as of December 2025):

npx nuxi module add nuxt-studio@beta

This adds @nuxt/studio to devDependencies and configures the module in nuxt.config.ts.

2. Verify Module Configuration

Check that nuxt.config.ts includes the Studio module:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@nuxt/content',
    '@nuxt/studio'  // Added automatically
  ]
})

3. Start Development Mode

Run the development server to test Studio locally:

npm run dev
# or
bun dev

Access Studio at http://localhost:3000/_studio (development mode).

OAuth Authentication Setup

Studio requires OAuth authentication for production deployments. Choose one provider:

Supported Providers

• GitHub OAuth: Best for public repositories and GitHub-hosted projects
• GitLab OAuth: Ideal for self-hosted GitLab instances
• Google OAuth: Universal option for any setup

Quick OAuth Configuration

For detailed OAuth setup instructions for each provider, load references/oauth-providers.md.

Environment variables pattern (all providers):

# GitHub
NUXT_OAUTH_GITHUB_CLIENT_ID=your_client_id
NUXT_OAUTH_GITHUB_CLIENT_SECRET=your_client_secret

# GitLab
NUXT_OAUTH_GITLAB_CLIENT_ID=your_client_id
NUXT_OAUTH_GITLAB_CLIENT_SECRET=your_client_secret

# Google
NUXT_OAUTH_GOOGLE_CLIENT_ID=your_client_id
NUXT_OAUTH_GOOGLE_CLIENT_SECRET=your_client_secret

Callback URL pattern:

https://studio.yourdomain.com/api/auth/callback/[provider]

Replace [provider] with: github, gitlab, or google.

For complete OAuth app creation steps, consult references/oauth-providers.md.

Cloudflare Deployment

Studio works excellently on Cloudflare Pages and Workers. Use the Cloudflare deployment for:

• Serverless edge deployment
• Custom subdomain routing (e.g., studio.domain.com)
• Environment variable management via dashboard
• Automatic builds from Git

Cloudflare Setup Overview

1. Configure Nitro preset for Cloudflare in nuxt.config.ts
2. Create or update wrangler.toml for Workers deployment (optional)
3. Set environment variables on Cloudflare dashboard
4. Configure custom domain and subdomain routing
5. Deploy via Cloudflare Pages or Workers

For complete Cloudflare deployment instructions, load references/cloudflare-deployment.md.

Quick Cloudflare Configuration

Set the Cloudflare Pages preset:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/content', '@nuxt/studio'],

  nitro: {
    preset: 'cloudflare-pages'
  }
})

For Workers deployment with custom subdomain routing, see references/cloudflare-deployment.md.

Editor Types

Studio provides three editor types that can be configured per content type:

1. Monaco Editor: Code editor for markdown, YAML, JSON
2. TipTap Editor: Visual WYSIWYG editor with MDC component support (default)
3. Form Editor: Schema-driven form for YAML/JSON files

Configure Default Editor

// nuxt.config.ts
export default defineNuxtConfig({
  studio: {
    editor: {
      default: 'tiptap'  // or 'monaco' or 'form'
    }
  }
})

For detailed editor configuration options, load references/editor-configuration.md.

Subdomain Configuration

Deploy Studio to a subdomain for production use:

Common patterns:

• studio.yourdomain.com
• cms.yourdomain.com
• edit.yourdomain.com
• admin.yourdomain.com

DNS Setup

1. Add a CNAME record in your DNS provider
2. Point subdomain to Cloudflare Pages deployment
3. Configure custom domain in Cloudflare Pages settings

For complete subdomain setup with Cloudflare, load references/subdomain-setup.md.

Top 5 Common Errors

1. OAuth Redirect URI Mismatch

Error: Authentication loop or "redirect_uri_mismatch" error

Cause: OAuth app callback URL doesn't match actual deployment URL

Solution:

Ensure OAuth app callback URL is:
https://studio.yourdomain.com/api/auth/callback/[provider]

Not:
https://yourdomain.com/api/auth/callback/[provider]

2. Module Not Found: @nuxt/studio

Error: Cannot find module '@nuxt/studio'

Cause: Studio module not installed or installed incorrectly

Solution:

npx nuxi module add nuxt-studio@beta
# or
npm install -D @nuxt/studio

3. Cloudflare Pages Build Failure

Error: Build fails with "Incompatible module" or runtime errors

Cause: Nitro preset not configured for Cloudflare

Solution:

// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    preset: 'cloudflare-pages'
  }
})

4. Authentication Loop After Login

Error: Redirects to login repeatedly after successful OAuth

Cause: Session cookies not persisting due to domain mismatch

Solution:

• Verify NUXT_PUBLIC_STUDIO_URL environment variable matches deployment URL
• Check cookie settings in browser (must allow third-party cookies for OAuth)
• Ensure deployment URL uses HTTPS (not HTTP)