BlocksWeb Developer Docs

Appearance

Deploy to Vercel ​

Vercel is the recommended platform for deploying BlocksWeb applications. This guide covers everything you need to know to deploy your BlocksWeb site to Vercel.

Prerequisites ​

Before deploying, ensure you have:

  • A BlocksWeb project ready for deployment
  • A Vercel account
  • Your project in a Git repository (GitHub, GitLab, or Bitbucket)
  • BlocksWeb API credentials

Quick Deploy ​

The fastest way to deploy is using the Vercel CLI:

bash
# Install Vercel CLI
npm i -g vercel

# Deploy from your project directory
vercel

Follow the prompts to:

  1. Link to your Vercel account
  2. Configure project settings
  3. Set environment variables
  4. Deploy

Deploy via Git Integration ​

For automatic deployments on every push:

Step 1: Push to Git ​

Make sure your code is in a Git repository:

bash
git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/yourusername/your-repo.git
git push -u origin main

Step 2: Import to Vercel ​

  1. Go to https://vercel.com/new
  2. Click "Import Project"
  3. Select your Git provider (GitHub, GitLab, or Bitbucket)
  4. Find and import your repository

Step 3: Configure Project ​

Vercel will auto-detect Next.js. Verify these settings:

  • Framework Preset: Next.js
  • Build Command: next build (default)
  • Output Directory: .next (default)
  • Install Command: npm install (or your preferred package manager)

Step 4: Add Environment Variables ​

Click "Environment Variables" and add:

bash
BLOCKSWEB_API_KEY=your_api_key_here
BLOCKSWEB_WORKSPACE_ID=your_workspace_id_here

Optional variables:

bash
# Custom API URL (if self-hosting)
BLOCKSWEB_API_URL=https://api.yoursite.com

# Feature flags
BLOCKSWEB_ENABLE_ANALYTICS=true
BLOCKSWEB_ENABLE_AB_TESTING=true

# Other Next.js environment variables
NEXT_PUBLIC_SITE_URL=https://yoursite.com

Step 5: Deploy ​

Click "Deploy" and wait for the build to complete. Vercel will:

  1. Clone your repository
  2. Install dependencies
  3. Run the build command
  4. Deploy to production

Your site will be live at https://your-project.vercel.app.

Custom Domain ​

To add a custom domain:

1. Go to Project Settings ​

In your Vercel dashboard:

  1. Select your project
  2. Go to Settings → Domains

2. Add Domain ​

  1. Click "Add"
  2. Enter your domain (e.g., yoursite.com)
  3. Click "Add"

3. Configure DNS ​

Vercel will provide DNS records. Add them to your domain registrar:

For root domain (yoursite.com):

  • Type: A
  • Name: @
  • Value: 76.76.21.21

For www subdomain:

  • Type: CNAME
  • Name: www
  • Value: cname.vercel-dns.com

DNS propagation can take up to 48 hours.

4. Verify ​

Once DNS propagates, Vercel will automatically provision an SSL certificate.

Environment-Specific Configuration ​

Production vs Preview ​

Use different API keys for production and preview deployments:

bash
# Production (main branch)
BLOCKSWEB_API_KEY=bw_live_production_key

# Preview (all other branches)
BLOCKSWEB_API_KEY=bw_live_preview_key

In Vercel, set environment variables with specific scopes:

  • Production: Only main branch
  • Preview: All other branches
  • Development: Local development (not used on Vercel)

Branch-Specific Variables ​

For different staging environments:

  1. Go to Settings → Environment Variables
  2. Click "Add"
  3. Set "Environments": Select "Preview"
  4. Optional: Set "Git Branch": Specify branch name

Build Configuration ​

Custom Build Command ​

If you need custom build steps:

json
// package.json
{
  "scripts": {
    "build": "next build",
    "build:production": "next build && node scripts/post-build.js",
    "build:preview": "next build --no-lint"
  }
}

In Vercel settings, override the build command:

bash
npm run build:production

Build Output API ​

For advanced caching and optimization:

javascript
// next.config.js
module.exports = {
  output: 'standalone', // Optimized Docker images
};

Edge Runtime ​

To use Vercel Edge Runtime:

typescript
// app/[[...path]]/page.tsx
export const runtime = 'edge';

export default function Page() {
  // Your page component
}

Performance Optimization ​

Image Optimization ​

BlocksWeb images work automatically with Next.js Image Optimization:

typescript
import { Image } from '@blocksweb/core/client';

// Images are automatically optimized by Vercel
<Image
  propName="heroImage"
  asset={heroImage}
  alt="Hero"
/>

Caching Strategy ​

Configure caching headers:

typescript
// next.config.js
module.exports = {
  async headers() {
    return [
      {
        source: '/:path*',
        headers: [
          {
            key: 'Cache-Control',
            value: 's-maxage=60, stale-while-revalidate=3600',
          },
        ],
      },
    ];
  },
};

ISR (Incremental Static Regeneration) ​

For better performance, use ISR:

typescript
// app/[[...path]]/page.tsx
export const revalidate = 60; // Revalidate every 60 seconds

export default async function Page({ params }) {
  // Fetch page data
  return <Canvas path={path} />;
}

Monitoring ​

Analytics ​

Enable Vercel Analytics:

bash
npm install @vercel/analytics
typescript
// app/layout.tsx
import { Analytics } from '@vercel/analytics/react';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Analytics />
      </body>
    </html>
  );
}

Speed Insights ​

Enable Vercel Speed Insights:

bash
npm install @vercel/speed-insights
typescript
// app/layout.tsx
import { SpeedInsights } from '@vercel/speed-insights/next';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <SpeedInsights />
      </body>
    </html>
  );
}

Continuous Deployment ​

With Git integration enabled:

  • Push to main → Automatic production deployment
  • Push to other branches → Automatic preview deployment
  • Pull requests → Automatic preview URLs

Deployment Protection ​

Protect production deployments:

  1. Go to Settings → Git
  2. Enable "Production Branch" protection
  3. Require approvals before merging to main

Preview Deployments ​

Every branch and PR gets a unique URL:

https://your-project-git-feature-branch-username.vercel.app

Share this URL with stakeholders for review.

Troubleshooting ​

Build Fails ​

Check build logs:

  1. Go to Deployments
  2. Click on the failed deployment
  3. Review "Build Logs"

Common issues:

TypeScript errors:

bash
# Fix: Run type check locally
npm run type-check

Missing environment variables:

bash
# Fix: Add to Vercel dashboard under Environment Variables

Out of memory:

javascript
// next.config.js
module.exports = {
  // Increase memory limit
  experimental: {
    largePageDataBytes: 128 * 1000,
  },
};

Environment Variables Not Working ​

Make sure:

  1. Variables are added in Vercel dashboard
  2. Correct environment scope (Production/Preview/Development)
  3. Redeploy after adding variables

Variables prefixed with NEXT_PUBLIC_ are exposed to the browser:

bash
# Server-side only
BLOCKSWEB_API_KEY=secret

# Available in browser
NEXT_PUBLIC_SITE_URL=https://yoursite.com

404 on Catch-All Routes ​

Ensure your catch-all route is configured correctly:

app/[[...path]]/page.tsx  ✅ Correct
app/[...path]/page.tsx    ❌ Won't match root `/`

Slow Build Times ​

Optimize builds:

  1. Use pnpm instead of npm:

    json
    // package.json
{
  "packageManager": "pnpm@8.0.0"
}

  2. Enable caching:

    javascript
    // next.config.js
module.exports = {
  experimental: {
    turbotrace: true,
  },
};

  3. Reduce dependencies:

    bash
    npm prune --production

Advanced Configuration ​

Monorepo Support ​

For Turborepo or pnpm workspaces:

json
// vercel.json
{
  "buildCommand": "cd ../.. && npx turbo run build --filter=website",
  "outputDirectory": ".next",
  "installCommand": "pnpm install"
}

Custom Vercel Configuration ​

Create vercel.json:

json
{
  "buildCommand": "npm run build",
  "devCommand": "npm run dev",
  "installCommand": "npm install",
  "framework": "nextjs",
  "regions": ["iad1", "sfo1"],
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        {
          "key": "X-Frame-Options",
          "value": "DENY"
        }
      ]
    }
  ]
}

Edge Config ​

For dynamic configuration:

typescript
import { get } from '@vercel/edge-config';

export default async function Page() {
  const config = await get('feature-flags');
  // Use config
}

Cost Optimization ​

Vercel pricing is based on:

  • Build minutes
  • Serverless function invocations
  • Bandwidth
  • Edge middleware invocations

Optimize costs:

  1. Use ISR instead of SSR where possible
  2. Cache aggressively for static content
  3. Optimize images to reduce bandwidth
  4. Use Edge Runtime for better performance

Free tier includes:

  • 100 GB bandwidth
  • 100 hours build time
  • 1000 serverless function invocations per day

Security ​

Secure Environment Variables ​

Never expose secrets in client-side code:

typescript
// ❌ BAD - Exposed to browser
const apiKey = process.env.NEXT_PUBLIC_BLOCKSWEB_API_KEY;

// ✅ GOOD - Server-side only
const apiKey = process.env.BLOCKSWEB_API_KEY;

Security Headers ​

Add security headers in next.config.js:

javascript
module.exports = {
  async headers() {
    return [
      {
        source: '/:path*',
        headers: [
          { key: 'X-DNS-Prefetch-Control', value: 'on' },
          { key: 'X-Frame-Options', value: 'SAMEORIGIN' },
          { key: 'X-Content-Type-Options', value: 'nosniff' },
          { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
        ],
      },
    ];
  },
};

Next Steps ​

Resources ​