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:

• Nuxt Version: ≥3.x (Studio requires Nuxt 3)

• @nuxt/content Module: ≥2.x (required dependency)

• Node.js: ≥18.x recommended

• 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

• Configure Nitro preset for Cloudflare in nuxt.config.ts

• Create or update wrangler.toml for Workers deployment (optional)

• Set environment variables on Cloudflare dashboard

• Configure custom domain and subdomain routing

• 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:

• Monaco Editor: Code editor for markdown, YAML, JSON

• TipTap Editor: Visual WYSIWYG editor with MDC component support (default)

• 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

• Add a CNAME record in your DNS provider

• Point subdomain to Cloudflare Pages deployment

• 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)

5. Subdomain Routing Not Working

Error: Studio loads on main domain instead of subdomain

Cause: DNS/wrangler configuration incorrect

Solution:

• Verify CNAME record points to Cloudflare Pages

• Check custom domain configuration in Cloudflare dashboard

• For Workers: verify wrangler.toml routes configuration

For complete error catalog and solutions, load references/troubleshooting.md .

Working with Templates

The skill includes working configuration templates:

• templates/nuxt.config.ts : Complete Studio module configuration

• templates/wrangler.toml : Cloudflare Workers deployment config

• templates/studio-auth-github.ts : GitHub OAuth implementation

• templates/studio-auth-gitlab.ts : GitLab OAuth implementation

• templates/studio-auth-google.ts : Google OAuth implementation

Use these as starting points for your Studio setup.

Development Workflow

Local Development

• Install Studio module: npx nuxi module add nuxt-studio@beta

• Start dev server: npm run dev

• Access Studio: http://localhost:3000/_studio

• Edit content visually

• Commit changes from Studio UI

Production Deployment

• Configure OAuth provider (GitHub/GitLab/Google)

• Set environment variables on deployment platform

• Configure Nitro preset for target platform

• Deploy to Cloudflare Pages/Workers or other platform

• Set up custom subdomain

• Test authentication and content editing

Validation Checklist

Before deploying Studio to production:

• Nuxt Content installed and configured (≥v2.x)

• Nuxt version ≥3.x

• @nuxt/studio module installed

• OAuth provider configured with valid credentials

• Environment variables set correctly

• Nitro preset configured for deployment platform

• Custom subdomain DNS configured

• Callback URLs match deployment URL

• Studio accessible at subdomain URL

• Authentication working correctly

• Content editing and commit functionality tested

When to Load References

Load reference files when working on specific aspects:

• OAuth setup: Load references/oauth-providers.md for detailed GitHub/GitLab/Google OAuth app creation

• Cloudflare deployment: Load references/cloudflare-deployment.md for complete Cloudflare Pages/Workers setup with wrangler, custom domains, and environment variables

• Editor configuration: Load references/editor-configuration.md for Monaco/TipTap/Form editor customization

• Subdomain setup: Load references/subdomain-setup.md for DNS and routing configuration

• Troubleshooting: Load references/troubleshooting.md for comprehensive error solutions and debugging

Utility Scripts

Use the included scripts for common operations:

• scripts/check-prerequisites.sh : Verify Nuxt Content and version requirements

• scripts/validate-config.sh : Check nuxt.config.ts Studio configuration

• scripts/test-oauth.sh : Test OAuth environment variables setup

Run scripts with:

bash $CLAUDE_PLUGIN_ROOT/skills/nuxt-studio/scripts/script-name.sh

Integration with Other Skills

This skill works well with:

• nuxt-content: Prerequisites for Studio (content module required)

• nuxt-v4: Core Nuxt framework knowledge for configuration

• cloudflare-worker-base: Cloudflare deployment fundamentals

• better-auth: Alternative authentication patterns if custom auth needed

Additional Resources

• Nuxt Studio Repository: https://github.com/nuxt-content/studio

• Nuxt Content Documentation: https://content.nuxt.com

• Cloudflare Pages: https://pages.cloudflare.com

• OAuth Documentation: GitHub/GitLab/Google developer docs

Version Information

• Nuxt Studio: v1.0.0-beta.3 (latest as of December 2025)

• Nuxt: ≥3.x required

• @nuxt/content: ≥2.x required

• Node.js: ≥18.x recommended

For the latest version information, check: https://github.com/nuxt-content/studio/releases

Next steps: After Studio is configured, test the deployment thoroughly, ensure OAuth authentication works correctly, and verify that content editing and Git commits function as expected.