Set up Vercel preview subdomain with auto-sync branch and SEO protection. Pattern: {repo-name}-preview.jbcloud.app
Configures a Vercel preview subdomain with automatic branch synchronization and SEO protection via robots.txt and response headers.
When to use
Use this when you need a stable, non-production preview environment for a web project that automatically updates from any branch and blocks search engine indexing.
How to invoke
manual via /setup-preview, auto-invoked when relevant
/plugin marketplace add https://www.claudepluginhub.com/api/plugins/aventerica89-claude-codex/marketplace.json/plugin install aventerica89-claude-codex@cpd-aventerica89-claude-codexConfigure a stable preview subdomain on Vercel with automatic branch sync and search engine blocking.
/setup-preview # Auto-detect repo name
/setup-preview --subdomain custom-name # Custom subdomain
/setup-preview --dry-run # Show what would be created
Parse $ARGUMENTS for:
--subdomain <name> or -s - Override the auto-generated subdomain name--dry-run or -d - Preview changes without creating files--branch <name> - Use a different branch name (default: preview){repo-name}-preview.jbcloud.app
The repo name is sanitized:
claude-codex → claudecodex-preview.jbcloud.appHDFlowsheet-Cloud → hdflowsheetcloud-preview.jbcloud.appjb-cloud-docs → jbclouddocs-preview.jbcloud.appCheck for config files:
| Framework | Config File | robots.txt Location |
|---|---|---|
| Next.js | next.config.* | app/robots.ts |
| Astro | astro.config.* | src/pages/robots.txt.ts |
| Remix | remix.config.* | app/routes/robots[.]txt.ts |
| SvelteKit | svelte.config.* | src/routes/robots.txt/+server.ts |
| Static | None | Skip robots handler |
# From git remote
git remote get-url origin | sed 's/.*\/\([^/]*\)\.git/\1/' | tr -d '-' | tr '[:upper:]' '[:lower:]'
Merge headers config with existing vercel.json:
{
"headers": [
{
"source": "/(.*)",
"has": [
{
"type": "host",
"value": "{sanitized-repo-name}-preview.jbcloud.app"
}
],
"headers": [
{
"key": "X-Robots-Tag",
"value": "noindex, nofollow"
}
]
}
]
}
Next.js (app/robots.ts):
import type { MetadataRoute } from 'next'
export default function robots(): MetadataRoute.Robots {
const isProduction = process.env.VERCEL_GIT_COMMIT_REF === 'main'
return isProduction
? { rules: { userAgent: '*', allow: '/' } }
: { rules: { userAgent: '*', disallow: '/' } }
}
Astro (src/pages/robots.txt.ts):
import type { APIRoute } from 'astro';
export const GET: APIRoute = () => {
const isProduction = process.env.VERCEL_GIT_COMMIT_REF === 'main';
const robotsTxt = isProduction
? `User-agent: *\nAllow: /`
: `User-agent: *\nDisallow: /`;
return new Response(robotsTxt, {
headers: { 'Content-Type': 'text/plain; charset=utf-8' },
});
};
Create .github/workflows/preview.yml:
name: Sync Preview Branch
on:
push:
branches-ignore:
- preview
permissions:
contents: write
jobs:
sync-preview:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Sync to preview branch
run: |
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
git fetch origin preview || git checkout -b preview
git checkout preview
git reset --hard ${{ github.sha }}
git push -f origin preview
## Preview Subdomain Setup
**Repository**: {repo-name}
**Framework**: {Next.js/Astro/etc}
**Subdomain**: {sanitized-name}-preview.jbcloud.app
### Files Created/Modified
| File | Action |
|------|--------|
| `vercel.json` | Updated (added headers) |
| `app/robots.ts` | Created |
| `.github/workflows/preview.yml` | Created |
### Manual Steps Required
Complete these in Vercel Dashboard:
1. **Add Domain**
- Go to: Project Settings → Domains
- Add: `{subdomain}-preview.jbcloud.app`
2. **Assign to Branch**
- Click Edit on the domain
- Set Git Branch: `preview`
- Save
3. **Enable System Env Vars**
- Go to: Project Settings → Environment Variables
- Enable: "Automatically expose System Environment Variables"
### Verification
After completing manual steps:
1. Push to any branch
2. Check GitHub Actions completed
3. Visit: https://{subdomain}-preview.jbcloud.app
4. Verify `X-Robots-Tag: noindex` in response headers
### Ready!
Production: https://{production-domain}
Preview: https://{subdomain}-preview.jbcloud.app
User: /setup-preview
Claude: Detecting project configuration...
## Preview Subdomain Setup
**Repository**: claude-codex
**Framework**: Astro
**Subdomain**: claudecodex-preview.jbcloud.app
### Files Created/Modified
| File | Action |
|------|--------|
| `landing/vercel.json` | Updated (added headers) |
| `landing/src/pages/robots.txt.ts` | Created |
| `.github/workflows/preview.yml` | Created |
### Manual Steps Required
1. **Add Domain** in Vercel: `claudecodex-preview.jbcloud.app`
2. **Assign to Branch**: `preview`
3. **Enable System Env Vars**: "Automatically expose System Environment Variables"
Ready! Push to any branch to trigger the preview sync.
Developer pushes to any branch
│
▼
GitHub Actions triggers
│
▼
Force-pushes commit to `preview` branch
│
▼
Vercel detects push to `preview`
│
▼
Deploys to {repo}-preview.jbcloud.app
│
▼
Headers block search indexing
preview branch is auto-managed - don't commit directly to itThis command was successfully tested on the claude-codex project:
| Component | Value |
|---|---|
| Production | codex.jbcloud.app |
| Preview | claudecodex-preview.jbcloud.app |
| Framework | Astro |
| Branch | preview (auto-synced) |
Files created:
landing/vercel.json - noindex headers for preview hostlanding/src/pages/robots.txt.ts - Dynamic robots based on branch.github/workflows/preview.yml - Auto-sync workflowFor *.jbcloud.app subdomains to work with Vercel:
Cloudflare DNS (if using Cloudflare for jbcloud.app):
Type: CNAME
Name: *
Target: cname.vercel-dns.com
Proxy: DNS only (gray cloud)
Or per-subdomain:
Type: CNAME
Name: claudecodex-preview
Target: cname.vercel-dns.com
The workflow creates the branch on first push. Either:
git checkout -b preview && git push -u origin previewThe workflow needs contents: write permission. Verify the workflow includes:
permissions:
contents: write
gh run list --workflow="Sync Preview Branch"preview branch in VercelVercel headers only apply when the has condition matches. Verify:
vercel.json headers configvercel.json was updated/deploy-check - Pre-deployment verification/setup-github-actions - Configure other workflows/jbdocs - Sync documentation (includes preview setup option)