Nuxt Studio

Nuxt Studio

Self-hosted, open-source CMS module for editing Nuxt Content websites in production.

When to Use

Working with:

• Installing and configuring nuxt-studio module
• Authentication providers (GitHub, GitLab, Google OAuth, SSO, custom)
• Git provider setup (GitHub, GitLab, branch config)
• Visual content editing (MDC components, YAML/JSON forms, frontmatter)
• Media management (public dir, NuxtHub blob, S3, R2)
• Publishing flow (draft layer, conflict detection, CI/CD rebuild)
• AI-powered content assistance (Vercel AI Gateway)

For content collections/queries: use nuxt-content skill For NuxtHub storage/database: use nuxthub skill For Nuxt basics: use nuxt skill

Available Guidance

Read specific files based on current work:

• [references/configuration.md](references/configuration.md) - Module setup, auth providers, Git providers, environment variables
• [references/live-editing.md](references/live-editing.md) - Visual editor, media management, MDC components, AI features
• [references/deployment.md](references/deployment.md) - SSR requirements, Git publishing, branch strategies, CI/CD

Loading Files

Consider loading these reference files based on your task:

• [ ] references/configuration.md - if installing, configuring auth/git providers, or setting env vars
• [ ] references/live-editing.md - if working with content editor, media, components, or AI features
• [ ] references/deployment.md - if deploying, configuring branches, or troubleshooting publish flow

DO NOT load all files at once. Load only what's relevant to your current task.

Key Concepts

Quick Start

npx nuxt module add nuxt-studio

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/content', 'nuxt-studio'],
  studio: {
    repository: {
      provider: 'github',
      owner: 'your-username',
      repo: 'your-repo',
      branch: 'main',
    },
  },
})

# .env
STUDIO_GITHUB_CLIENT_ID=<client_id>
STUDIO_GITHUB_CLIENT_SECRET=<client_secret>

Access Studio at https://your-site.com/_studio (default route).

Official Documentation

• Nuxt Studio: https://nuxt.studio
• Setup: https://nuxt.studio/setup
• GitHub: https://github.com/nuxt-content/nuxt-studio

Token Efficiency

Main skill: ~300 tokens. Each sub-file: ~800-1200 tokens. Only load files relevant to current task.

Configuration

When to Use

Installing Nuxt Studio, configuring auth/git providers, setting up environment variables, or customizing module options.

Installation

npx nuxt module add nuxt-studio

Requires @nuxt/content and SSR-capable hosting (nuxt build, not static-only).

Module Options

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/content', 'nuxt-studio'],
  studio: {
    route: '/_studio', // Admin route (default)
    dev: true, // Enable in dev (default), set false to test prod locally
    i18n: { defaultLocale: 'en' }, // 23 languages supported
    git: {
      commit: { messagePrefix: 'content:' }, // Prefix all commits
    },
    media: {
      external: false, // Enable NuxtHub blob storage
      maxFileSize: 10, // MB
      allowedTypes: ['image/*', 'video/*', 'audio/*'],
      prefix: 'studio', // Bucket path prefix
    },
    meta: {
      components: {
        include: ['Content*', 'Landing*'],
        exclude: ['HiddenComponent'],
        groups: [
          { label: 'Content', include: ['content*'] },
          { label: 'UI', include: ['app/components/ui/**'] },
        ],
        ungrouped: 'include',
      },
    },
  },
})

Auth Providers

GitHub OAuth

# .env
STUDIO_GITHUB_CLIENT_ID=<client_id>
STUDIO_GITHUB_CLIENT_SECRET=<client_secret>
STUDIO_GITHUB_MODERATORS=admin@example.com,editor@example.com  # Optional whitelist
STUDIO_GITHUB_INSTANCE_URL=https://gh-ent.com  # GitHub Enterprise

Callback URL: https://yourdomain.com/__nuxt_studio/auth/github Git operations use the OAuth token automatically.

GitLab OAuth

STUDIO_GITLAB_APPLICATION_ID=<app_id>
STUDIO_GITLAB_APPLICATION_SECRET=<secret>
STUDIO_GITLAB_MODERATORS=admin@example.com  # Optional
STUDIO_GITLAB_INSTANCE_URL=https://gitlab.company.com  # Self-hosted

Callback URL: https://yourdomain.com/__nuxt_studio/auth/gitlab Requires api scope.

Google OAuth

STUDIO_GOOGLE_CLIENT_ID=<client_id>
STUDIO_GOOGLE_CLIENT_SECRET=<client_secret>
STUDIO_GOOGLE_MODERATORS=admin@example.com  # REQUIRED
STUDIO_GITHUB_TOKEN=<pat>  # PAT needed — Google doesn't provide Git access

Callback URL: https://yourdomain.com/__nuxt_studio/auth/google

SSO Server

Deploy nuxt-studio-sso independently:

STUDIO_SSO_URL=https://your-sso-server.com
STUDIO_SSO_CLIENT_ID=<client_id>
STUDIO_SSO_CLIENT_SECRET=<client_secret>

Custom Auth

// server/api/login.post.ts
import { setStudioUserSession } from '#imports'

export default eventHandler(async (event) => {
  const { email, password } = await readBody(event)
  const user = await validateCredentials(email, password)
  if (!user) throw createError({ statusCode: 401, message: 'Invalid credentials' })

  await setStudioUserSession(event, {
    providerId: user.id, name: user.name, email: user.email, avatar: user.avatar || '',
  })
  return { ok: true }
})

Logout: call clearStudioUserSession(event). Requires PAT for Git operations.

Git Provider Setup

studio: {
  repository: {
    provider: 'github', // or 'gitlab'
    owner: 'your-username',
    repo: 'your-repo',
    branch: 'main',
    rootDir: 'docs', // Monorepo support
    private: true, // Set false to limit OAuth to public repos
    instanceUrl: 'https://gh-ent.com', // Enterprise/self-hosted
  },
}

Auto-detected on Vercel, Netlify, GitHub Actions, GitLab CI from platform env vars. Manual config overrides auto-detection.

Auth Hooks

// server/plugins/studio-auth.ts
export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('studio:auth:login', async ({ user, event }) => {
    console.log(`${user.email} logged in`)
  })
  nitroApp.hooks.hook('studio:auth:logout', async ({ user, event }) => {
    console.log(`${user.email} logged out`)
  })
})

Provider Comparison

Multiple providers can be used simultaneously (e.g., GitHub for devs + Google for editors).

Resources

• Setup: https://nuxt.studio/setup
• Auth providers: https://nuxt.studio/auth-providers
• Git providers: https://nuxt.studio/git-providers

Deployment

When to Use

Deploying a Nuxt Studio site, configuring Git publishing, setting up branch strategies, or troubleshooting the publish flow.

Requirements

• SSR hosting required — Studio needs server-side routes for authentication. Deploy with nuxt build, not static-only generation.
• Nuxt Content — @nuxt/content must be installed and configured.
• Supported platforms: Vercel, Netlify, Cloudflare Pages, any Node.js SSR host.

Publishing Flow

1. Editor makes changes → stored as drafts in IndexedDB (browser-local) 2. Editor clicks Publish → Studio commits drafts to Git via provider API 3. CI/CD detects commit → rebuilds and redeploys automatically 4. Studio detects new deployment → notifies editors

No webhooks to configure — publishing uses the Git provider's API directly, and deployment relies on your existing CI/CD pipeline.

Git Repository Config

// nuxt.config.ts
export default defineNuxtConfig({
  studio: {
    repository: {
      provider: 'github', // or 'gitlab'
      owner: 'your-username',
      repo: 'your-repo',
      branch: 'main',
    },
  },
})

Auto-Detection

On supported platforms, repository details auto-detect from CI env vars:

Manual config overrides auto-detection.

Branch Strategies

Direct to Production

Default. Commits go to main (or configured branch), triggering production rebuild:

studio: { repository: { branch: 'main' } }

Preview Branch

Publish to a staging branch, review on preview environment, then merge to production:

studio: {
  repository: {
    branch: process.env.STUDIO_BRANCH_NAME || 'content-preview',
  },
}

Environment-Based

Different branches per deployment environment:

studio: {
  repository: {
    branch: process.env.VERCEL_GIT_COMMIT_REF || 'main',
  },
}

Commit Configuration

studio: {
  git: {
    commit: {
      messagePrefix: 'content:', // Prepends to all Studio commits
    },
  },
}

Conflict Detection

Studio compares local drafts against the latest Git version before publishing. Conflicts arise when:

• Multiple editors modify the same files during active builds
• Deployments fail, leaving production database out of sync with Git

Studio warns editors and prevents overwriting newer changes.

Platform-Specific Setup

Vercel

// nuxt.config.ts — repository auto-detected
export default defineNuxtConfig({
  modules: ['@nuxt/content', 'nuxt-studio'],
  // studio.repository auto-populated from VERCEL_GIT_* env vars
})

Set STUDIO_GITHUB_CLIENT_ID and STUDIO_GITHUB_CLIENT_SECRET in Vercel project settings.

Netlify

// nuxt.config.ts — repository auto-detected from REPOSITORY_URL
export default defineNuxtConfig({
  modules: ['@nuxt/content', 'nuxt-studio'],
})

Cloudflare Pages

export default defineNuxtConfig({
  modules: ['@nuxt/content', 'nuxt-studio'],
  studio: {
    repository: {
      provider: 'github',
      owner: 'your-username',
      repo: 'your-repo',
      branch: process.env.CF_PAGES_BRANCH || 'main',
    },
  },
})

Pre-rendering (Optional)

If using hybrid rendering, ensure Studio routes aren't pre-rendered:

export default defineNuxtConfig({
  nitro: {
    prerender: {
      routes: ['/'],
      crawlLinks: true,
    },
  },
})

Studio's /_studio route requires SSR and handles itself automatically.

Monorepo Support

studio: {
  repository: {
    rootDir: 'docs', // Subdirectory containing the Nuxt project
  },
}

Troubleshooting

Resources

• Setup: https://nuxt.studio/setup
• Advanced sync: https://nuxt.studio/advanced
• Git providers: https://nuxt.studio/git-providers

Live Editing

When to Use

Working with the visual content editor, media management, MDC component editing, or AI content features.

Visual Editor

TipTap-based WYSIWYG editor that generates MDC syntax. Two editing modes:

• Visual editor — Notion-like block editing with drag-and-drop
• Code editor — Direct markdown/MDC editing

MDC Component Support

Insert Vue components in content, edit props visually, drag-and-drop blocks. Components in components/content/ are available in the editor.

Filter visible components:

// nuxt.config.ts
export default defineNuxtConfig({
  studio: {
    meta: {
      components: {
        include: ['Content*', 'Landing*'],
        exclude: ['InternalComponent'],
        groups: [
          { label: 'Content', include: ['content*'] },
          { label: 'Landing', include: ['landing*'] },
        ],
      },
    },
  },
})

Schema-Driven Forms

Frontmatter and YAML/JSON files get auto-generated form UIs based on collection schemas. Use .describe() for editor labels:

// content.config.ts
import { defineCollection, defineContentConfig, z } from '@nuxt/content'

export default defineContentConfig({
  collections: {
    blog: defineCollection({
      type: 'page',
      source: 'blog/**/*.md',
      schema: z.object({
        title: z.string().describe('Post title'),
        description: z.string().describe('SEO description'),
        image: z.string().describe('Cover image URL'),
        date: z.date().describe('Publication date'),
        tags: z.array(z.string()).describe('Post tags'),
      }),
    }),
  },
})

Draft System

Changes are stored as drafts in IndexedDB (browser-local, not shared across devices). Three-tier flow:

1. Production layer — SQLite WASM in browser, mirrors deployed content 2. Draft layer — IndexedDB via unstorage, stores unpublished edits 3. Git repository — Final destination when publishing

On load, drafts merge with the SQLite database to render a preview of your changes.

Preview

In development, file changes sync in real-time with local filesystem via WebSocket HMR.

In production, the draft layer overlays production content so editors see their changes before publishing.

Media Management

Access via the Media tab. Browse folders, upload files, drag-and-drop.

Default Storage (/public)

Zero config. Files committed to Git on publish. Best for small projects. A service worker intercepts media requests to display draft versions.

External Storage (NuxtHub Blob)

For larger projects — files stored in cloud, not committed to Git:

npx nuxi module add hub

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxthub/core', 'nuxt-studio'],
  hub: { blob: true },
  studio: {
    media: { external: true },
  },
})

Provider env vars:

# Vercel Blob
BLOB_READ_WRITE_TOKEN=your-token

# S3-compatible
S3_ACCESS_KEY_ID=key
S3_SECRET_ACCESS_KEY=secret
S3_BUCKET=bucket-name
S3_ENDPOINT=endpoint-url

Or Cloudflare R2:

hub: { blob: { driver: 'cloudflare-r2', bucketName: 'your-bucket' } }

Media Config Options

Supported: PNG, JPG, SVG, WebP, AVIF, GIF, MP4, MOV, WebM, MP3, WAV, AAC.

Editor Integration

• Slash command / → search "Image" for quick insertion
• Alt text support for SEO/a11y
• Custom width/height attributes

AI Content Assistance

Powered by Vercel AI Gateway. Provides context-aware content completion, transformation, and style guidance based on project context, cursor position, and active components.

Plug-and-play — no additional configuration needed beyond Vercel AI Gateway access.

Resources

• Content editing: https://nuxt.studio/content-editing
• Media: https://nuxt.studio/medias
• Introduction: https://nuxt.studio/introduction