/deploy-studio-cloudflare

name: nuxt-studio:deploy-cloudflare
description: Guide for deploying Nuxt Studio to Cloudflare Pages or Workers with custom subdomain routing
argument-hint: No arguments required - interactive deployment guide
allowed-tools: [Read, Write, Edit, Bash, AskUserQuestion]

Deploy Studio to Cloudflare

Comprehensive guide for deploying Nuxt Studio to Cloudflare Pages or Workers with subdomain configuration.

Execution Steps

1. Choose Deployment Method

Ask user:

**Question**: "Which Cloudflare deployment method do you prefer?"

• Header: "Deployment Type"
• Options:
• **Cloudflare Pages** (Recommended): "Git-integrated automatic deployments, easier setup"
• **Cloudflare Workers**: "Direct deployment with wrangler, more control"
• Multi-select: false

Store choice for later steps.

2. Verify Prerequisites

Check required tools and configuration:

**For Both Methods:**

• Cloudflare account exists
• Domain added to Cloudflare (for custom subdomain)
• OAuth credentials configured
• Nuxt Studio module installed

**For Workers Only:**

• wrangler CLI installed

Check wrangler installation:

wrangler --version

If not installed and Workers chosen:

wrangler is not installed. Install it with:

npm install -g wrangler
# or
bun add -g wrangler

Then run: wrangler login

Stop and wait for installation.

3. Configure Build Settings

Read nuxt.config.ts and verify Cloudflare preset:

Check for:

nitro: {
  preset: 'cloudflare-pages'  // or 'cloudflare' for Workers
}

If not set, ask user to confirm adding it:

"I need to configure the Nitro preset for Cloudflare. OK to update nuxt.config.ts?"

If approved, add/update:

**For Cloudflare Pages:**

nitro: {
  preset: 'cloudflare-pages'
}

**For Cloudflare Workers:**

nitro: {
  preset: 'cloudflare'
}

Use Edit tool to update nuxt.config.ts.

4. Build the Application

Run the build command:

npm run build

Monitor the build output for errors.

If build fails:

• Show error to user
• Check common issues:
• Missing dependencies
• Incompatible modules
• Configuration errors
• Suggest fixes based on error
• Offer to check references/troubleshooting.md

If build succeeds:

✓ Build completed successfully!

Output directory: .output/
- Public assets: .output/public
- Server code: .output/server

5A. Cloudflare Pages Deployment (if chosen)

Step 1: Git Repository Setup

Check if Git is configured:

git remote -v

If no remote:

Studio deployment requires a Git repository.

Initialize Git and push to GitHub/GitLab:

1. git init
2. git add .
3. git commit -m "Configure Studio for Cloudflare"
4. git remote add origin https://github.com/username/repo.git
5. git push -u origin main

Then re-run this command.

Stop and wait for Git setup.

If remote exists, continue.

Step 2: Create Pages Project

Provide instructions:

Create Cloudflare Pages Project:

1. Open Cloudflare Dashboard:
   https://dash.cloudflare.com

2. Navigate to: Workers & Pages → Create application → Pages → Connect to Git

3. Authenticate with GitHub/GitLab

4. Select your repository

5. Configure build settings:
   - Framework preset: Nuxt.js
   - Build command: npm run build
   - Build output directory: .output/public
   - Root directory: / (or your app subdirectory)

6. Click "Save and Deploy"

7. Wait for first deployment to complete

Step 3: Configure Environment Variables

Provide instructions:

Set Environment Variables in Cloudflare:

1. Go to: Workers & Pages → [Your Project] → Settings → Environment variables

2. Add these variables for Production:

   NUXT_OAUTH_[PROVIDER]_CLIENT_ID = [your_client_id]
   NUXT_OAUTH_[PROVIDER]_CLIENT_SECRET = [your_secret]
   NUXT_PUBLIC_STUDIO_URL = https://studio.yourdomain.com

3. For Preview environment (optional):
   - Add same variables with preview values
   - Use different OAuth app for preview

4. Click "Save"

5. Redeploy to apply variables:
   - Go to Deployments tab
   - Click "Retry deployment" on latest

IMPORTANT: Use the production OAuth credentials you configured earlier.

Ask user to confirm when done.

Step 4: Configure Custom Subdomain

Provide instructions:

Set Up Custom Subdomain:

1. In your Pages project, go to: Custom domains

2. Click "Set up a custom domain"

3. Enter your subdomain:
   studio.yourdomain.com
   (or the subdomain you chose during setup)

4. Click "Continue"

5. If domain is on Cloudflare DNS:
   - DNS record created automatically ✓
   - Shows "Active" status when ready

6. If domain on external DNS:
   - Add CNAME record:
     Name: studio
     Target: [project-name].pages.dev
   - Wait for DNS propagation (5-60 minutes)

7. Verify subdomain works:
   Visit: https://studio.yourdomain.com

Step 5: Update OAuth Callback URLs

Remind user:

⚠️ UPDATE OAUTH CALLBACK URLS

Your OAuth app callback URL must match the production URL:

For GitHub:
https://github.com/settings/developers
→ Update "Authorization callback URL" to:
https://studio.yourdomain.com/api/auth/callback/github

For GitLab:
https://gitlab.com/-/profile/applications
→ Update "Redirect URI" to:
https://studio.yourdomain.com/api/auth/callback/gitlab

For Google:
https://console.cloud.google.com/apis/credentials
→ Update "Authorized redirect URIs" to:
https://studio.yourdomain.com/api/auth/callback/google

This is CRITICAL for authentication to work!

5B. Cloudflare Workers Deployment (if chosen)

Step 1: Authenticate Wrangler

wrangler login

This opens browser for authentication.

Confirm user is logged in:

wrangler whoami

Step 2: Create/Update wrangler.toml

Check if wrangler.toml exists:

ls wrangler.toml

If not exists, offer to create from template:

"I'll create a wrangler.toml for your deployment. What is your domain name?"

Get domain from user, then create wrangler.toml:

name = "studio-