TutorialKit Production Deployment Guide

🚀 Quick Start

This repository is configured for zero-configuration deployment to Vercel with full WebContainer API support.

Prerequisites

Node.js 18.18.0 or higher
pnpm 8.15.6
Vercel account (free tier works)
GitHub account

📋 Deployment Checklist

✅ Pre-Deployment

Repository forked and cloned
Dependencies installed (pnpm install)
Build successful (pnpm build)
Tests passing (pnpm test)
Vercel configuration created
CI/CD pipeline configured
Environment variables documented

✅ Production Requirements

🔧 Manual Deployment to Vercel

Step 1: Install Vercel CLI

npm i -g vercel

Step 2: Login to Vercel

vercel login

Step 3: Link Project

vercel link

Step 4: Deploy to Production

vercel --prod

🤖 Automated Deployment (CI/CD)

GitHub Actions Pipeline

The repository includes a complete CI/CD pipeline that:

Quality Checks - Runs linting and tests
Build - Compiles all packages and documentation
Deploy - Pushes to Vercel production on main branch
Preview - Creates preview deployments for PRs

Required GitHub Secrets

Add these secrets to your GitHub repository:

Go to Settings → Secrets and variables → Actions
Add the following secrets:

Secret Name	Description	How to Get
`VERCEL_TOKEN`	Vercel authentication token	Create token
`VERCEL_ORG_ID`	Your Vercel organization ID	Run `vercel link` and check `.vercel/project.json`
`VERCEL_PROJECT_ID`	Your Vercel project ID	Run `vercel link` and check `.vercel/project.json`

Trigger Deployment

git add .
git commit -m "feat: deploy to production"
git push origin main

The pipeline will automatically:

Run quality checks
Build the application
Deploy to Vercel production
Generate deployment summary

🏗️ Build Configuration

Build Commands

{
  "installCommand": "pnpm install --frozen-lockfile",
  "buildCommand": "pnpm install && pnpm build",
  "outputDirectory": "docs/tutorialkit.dev/dist",
  "devCommand": "pnpm docs"
}

Build Process

Install Dependencies
```
pnpm install --frozen-lockfile
```
Build Core Packages
```
pnpm build
```
Builds all packages in the monorepo:
- @tutorialkit/astro
- @tutorialkit/react
- @tutorialkit/runtime
- @tutorialkit/theme
- @tutorialkit/types
Build Documentation Site
```
pnpm docs:build
```
Compiles the Astro-based documentation site with:
- Type checking
- Asset optimization
- Static site generation
- Header configuration

Output Structure

docs/tutorialkit.dev/dist/
├── _astro/          # Optimized assets (CSS, JS)
├── assets/          # Static assets
├── guides/          # Documentation pages
├── reference/       # API reference
├── _headers         # Security headers
└── index.html       # Entry point

🔒 Security Configuration

Cross-Origin Isolation

Required for WebContainer API:

{
  "Cross-Origin-Embedder-Policy": "require-corp",
  "Cross-Origin-Opener-Policy": "same-origin"
}

Additional Security Headers

{
  "X-Content-Type-Options": "nosniff",
  "X-Frame-Options": "DENY",
  "X-XSS-Protection": "1; mode=block",
  "Referrer-Policy": "strict-origin-when-cross-origin"
}

💾 Caching Strategy

Immutable Assets (1 year)

/assets/* - Static assets
/_astro/* - Astro build artifacts
*.js, *.css, *.woff2, etc. - Static files

Cache-Control: public, max-age=31536000, immutable

Service Worker (No cache)

Cache-Control: public, max-age=0, must-revalidate
Service-Worker-Allowed: /

🌐 Environment Variables

Production Environment

NODE_VERSION=18.18.0
PNPM_VERSION=8.15.6
NODE_OPTIONS=--max-old-space-size=4096
ASTRO_TELEMETRY_DISABLED=1
ENABLE_EXPERIMENTAL_COREPACK=1

WebContainer Configuration

CROSS_ORIGIN_EMBEDDER_POLICY=require-corp
CROSS_ORIGIN_OPENER_POLICY=same-origin

🧪 Testing Deployment

Local Preview

# Build production version
pnpm build
pnpm docs:build

# Preview locally
pnpm --filter=tutorialkit.dev preview

Verify WebContainer Support

Open browser DevTools
Check Console for errors

Verify headers:

fetch(window.location.href).then(r => {
  console.log(r.headers.get('cross-origin-embedder-policy'));
  console.log(r.headers.get('cross-origin-opener-policy'));
});

Test Service Workers

navigator.serviceWorker.getRegistrations().then(registrations => {
  console.log('Service Workers:', registrations);
});

📊 Monitoring & Analytics

Vercel Analytics

Automatically enabled for:

Page views
Performance metrics
Web Vitals (LCP, FID, CLS)
Error tracking

Build Logs

Access via:

Vercel Dashboard → Deployments → [Your Deployment] → Build Logs
GitHub Actions → Workflow runs → Build job

🔄 Rollback Procedure

Via Vercel Dashboard

Go to Deployments
Find previous successful deployment
Click ⋯ → Promote to Production

Via CLI

vercel rollback

Via GitHub

Revert the commit:
```
git revert HEAD
git push origin main
```
Pipeline will auto-deploy the reverted version

🐛 Troubleshooting

Build Failures

Issue: Out of memory during build

# Solution: Increase Node.js memory
NODE_OPTIONS=--max-old-space-size=8192 pnpm build

Issue: pnpm version mismatch

# Solution: Use exact version
pnpm install -g pnpm@8.15.6

WebContainer Issues

Issue: SharedArrayBuffer not available

Solution: Verify COOP/COEP headers are set correctly

Issue: Service Worker registration failed

Solution: Ensure HTTPS is enabled and SW cache headers are correct

Deployment Issues

Issue: Vercel deployment timeout

# Solution: Increase function timeout in vercel.json
{
  "functions": {
    "maxDuration": 60
  }
}

📚 Additional Resources

🎯 Performance Targets

Lighthouse Score: 95+ (all categories)
First Contentful Paint: < 1.5s
Time to Interactive: < 3.5s
Largest Contentful Paint: < 2.5s
Cumulative Layout Shift: < 0.1

✅ Production Readiness

✅ Zero-downtime deployment
✅ Automatic HTTPS
✅ Global CDN distribution
✅ Immutable builds
✅ Instant rollback
✅ Preview deployments
✅ Environment isolation
✅ Security headers
✅ Performance optimization
✅ Error tracking
✅ Analytics integration

Status: ✅ Production Ready

Last Updated: 2026-01-29

Deployment Target: Vercel

Framework: Astro + WebContainer API

FilesExpand file tree

DEPLOYMENT.md

Latest commit

History