Build & Deployment Guide

Complete guide to building and deploying the Cascadia Marquee website

Build & Deployment Guide

Complete guide to building and deploying the Cascadia Marquee website.

Development Commands

Core Development Commands

# Start development server with hot reload
pnpm dev
 
# Build for production
pnpm build
 
# Start production server
pnpm start
 
# Type check without building
pnpm type-check

Content and registry commands

# Build component registry
pnpm build:registry
 
# Regenerate navigation from content folders
pnpm build:navigation

MDX content is processed by Content Collections automatically when you run pnpm dev or pnpm build (no separate content build script).

Code Quality Commands

# Lint code
pnpm lint
 
# Fix linting issues automatically
pnpm lint:fix
 
# Check import order and fix
pnpm lint:imports

Build Process

Development Build

The development server (pnpm dev) starts Next.js with Turbopack. Content Collections compiles MDX when Next starts (via withContentCollections in next.config.ts).

pnpm dev

Use pnpm dev:webpack if you need the Webpack dev server instead of Turbopack.

Production Build

The production build (pnpm build) runs:

Registry generation - pnpm build:registry
Navigation generation - pnpm build:navigation
Next.js build - pnpm build:next (Content Collections processes MDX as part of this step)
Static generation - Pre-renders pages where generateStaticParams is defined

pnpm run build:registry && pnpm run build:navigation && pnpm run build:next

Build Output

The build process generates:

.next/
├── static/                 # Static assets
├── server/                 # Server-side code
├── standalone/             # Standalone build (if configured)
└── cache/                  # Build cache
 
.content-collections/       # Generated content types and collection data (gitignored)
src/__registry__/           # Component registry

Content Processing

Content Collections build

When Next.js starts or builds, @content-collections/next:

Scans src/content/** per collection in content-collections.ts
Validates front matter with Zod schemas
Compiles MDX (remark/rehype pipeline, Shiki, custom plugins)
Writes typed exports to .content-collections/generated
Exposes allDocs, allPosts, allLegalDocs, allServices via the content-collections import

MDX processing pipeline

Configuration lives in content-collections.ts and src/lib/content/compile-mdx-for-collections.ts:

// content-collections.ts (simplified)
import { defineCollection, defineConfig } from "@content-collections/core";
 
const posts = defineCollection({
  name: "posts",
  directory: "src/content/posts",
  include: "**/*.mdx",
  schema: z.object({ title: z.string(), summary: z.string(), content: z.string() }),
  transform: async (doc, { cache }) => ({
    ...doc,
    mdx: await cache(doc, (d) => compileMdxDocument(d, mdxPipeline), { key: "__mdx" }),
    slug: `/blog/${doc._meta.path}`,
  }),
});
 
export default defineConfig({ content: [docs, posts, legalDocs, services] });

Pages render compiled MDX with <Mdx code={doc.mdx} /> and use doc.content for table-of-contents and plain-text exports.

Component Registry Build

The registry build process:

Scans component directories (charts, examples)
Generates lazy-loaded imports for each component
Creates registry index with component metadata
Enables dynamic component loading

Deployment

Vercel Deployment (Recommended)

The site is configured for automatic deployment on Vercel:

Automatic Deployment

Main branch → Production deployment
Pull requests → Preview deployments
Environment variables configured in Vercel dashboard

Vercel Configuration

// vercel.json (if needed)
{
  "buildCommand": "pnpm build",
  "outputDirectory": ".next",
  "installCommand": "pnpm install",
  "framework": "nextjs"
}

Environment Variables

Configure these in Vercel dashboard:

# Canonical app URL (OAuth callbacks use APP_URL + fixed paths)
APP_URL=https://your-domain.com
NEXT_PUBLIC_APP_URL=https://your-domain.com
 
# Google Calendar Integration (redirect URI is built from APP_URL: .../api/google-calendar/oauth/callback)
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_CLIENT_EMAIL=your-service-account@project.iam.gserviceaccount.com
GOOGLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nYour private key here\n-----END PRIVATE KEY-----\n"
GOOGLE_CALENDAR_ID=your-email@gmail.com
 
# Email Service
RESEND_API_KEY=your_resend_api_key
 
# Analytics
NEXT_PUBLIC_GA_MEASUREMENT_ID=G-XXXXXXXXXX
NEXT_PUBLIC_CLARITY_PROJECT_ID=
 
# Facebook Pixel
FACEBOOK_PIXEL_ID=your_pixel_id

Manual Deployment

Build Locally

# Install dependencies
pnpm install
 
# Build the application
pnpm build
 
# Start production server
pnpm start

Deploy to Other Platforms

Netlify:

# Build command
pnpm build
 
# Publish directory
.next

Railway:

# Build command
pnpm build
 
# Start command
pnpm start

Docker:

FROM node:18-alpine
 
WORKDIR /app
 
COPY package*.json ./
RUN npm install
 
COPY . .
RUN npm run build
 
EXPOSE 3000
 
CMD ["npm", "start"]

Performance Optimization

Build Optimizations

Next.js Optimizations

// next.config.ts
const nextConfig = {
  // Enable experimental features
  experimental: {
    optimizePackageImports: ["lucide-react"],
  },
 
  // Image optimization
  images: {
    formats: ["image/webp", "image/avif"],
    remotePatterns: [
      {
        protocol: "https",
        hostname: "images.unsplash.com",
      },
    ],
  },
 
  // Bundle analysis
  webpack: (config, { isServer }) => {
    if (!isServer) {
      config.resolve.fallback = {
        ...config.resolve.fallback,
        fs: false,
      };
    }
    return config;
  },
};

Content Optimization

MDX processing with syntax highlighting
Image optimization with next/image
Font optimization with next/font
Code splitting for better performance

Runtime Optimizations

Static Generation

// Generate static pages at build time
export async function generateStaticParams() {
  const posts = await getPosts();
  return posts.map((post) => ({
    slug: post.slug,
  }));
}

Dynamic Imports

// Lazy load heavy components
const HeavyComponent = dynamic(() => import('./HeavyComponent'), {
  loading: () => <p>Loading...</p>,
});

Image Optimization

import Image from "next/image";
 
// Optimized image loading
<Image
  src="/blog-images/example.webp"
  alt="Description"
  width={800}
  height={600}
  priority={false} // Only for above-the-fold images
  placeholder="blur"
  blurDataURL="data:image/jpeg;base64,..."
/>;

Monitoring & Analytics

Google Analytics 4

GA4 loads from src/components/analytics/google-analytics.tsx after the visitor accepts Analytics cookies. Configure NEXT_PUBLIC_GA_MEASUREMENT_ID (and optionally Clarity) in your deployment environment.

For events, consent gating, and GA4 setup, see the Analytics & Tracking guide.

Error Monitoring

Error Boundaries

import { ErrorBoundary } from "react-error-boundary";
 
function ErrorFallback({ error, resetErrorBoundary }) {
  return (
    <div role="alert">
      <h2>Something went wrong:</h2>
      <pre>{error.message}</pre>
      <button onClick={resetErrorBoundary}>Try again</button>
    </div>
  );
}
 
export default function App() {
  return (
    <ErrorBoundary FallbackComponent={ErrorFallback}>
      <MyApp />
    </ErrorBoundary>
  );
}

Security

Environment Variables

Never commit .env.local to version control
Use Vercel dashboard for production environment variables
Rotate keys regularly for security
Use least privilege for API permissions

Content Security Policy

// next.config.ts
const nextConfig = {
  async headers() {
    return [
      {
        source: "/(.*)",
        headers: [
          {
            key: "Content-Security-Policy",
            value:
              "default-src 'self'; script-src 'self' 'unsafe-eval' 'unsafe-inline'; style-src 'self' 'unsafe-inline';",
          },
        ],
      },
    ];
  },
};

API Security

// API route with rate limiting
import { rateLimit } from "@/lib/rate-limit";
 
export default async function handler(req, res) {
  try {
    await rateLimit(req);
    // Handle request
  } catch (error) {
    res.status(429).json({ error: "Too many requests" });
  }
}

Troubleshooting

Build Issues

"Module not found" errors:

# Clear cache and reinstall
rm -rf node_modules .next
pnpm install
pnpm build

Content not building:

# Clear Next and Content Collections output, then rebuild
rm -rf .next .content-collections
pnpm build

Type errors:

# Check TypeScript
pnpm type-check

Deployment Issues

Environment variables not working:

Check Vercel dashboard configuration
Verify variable names match exactly
Ensure no extra spaces or quotes

Build failing on Vercel:

Check build logs in Vercel dashboard
Verify Node.js version compatibility
Check for memory limits

Images not loading:

Verify image paths are correct
Check next/image configuration
Ensure images are in public directory

Performance Issues

Slow build times:

Use --turbo flag for development
Check for unnecessary dependencies
Optimize content processing

Large bundle sizes:

Use dynamic imports for heavy components
Analyze bundle with @next/bundle-analyzer
Remove unused dependencies

Best Practices

Development

Use development commands for local development
Test builds locally before deploying
Keep dependencies updated regularly
Monitor build performance and optimize as needed

Deployment

Use automatic deployments for consistency
Test preview deployments before merging
Monitor production performance with analytics
Keep environment variables secure and up-to-date

Maintenance

Regular security updates for dependencies
Monitor error rates and performance metrics
Backup content and configuration
Document deployment procedures for team members

For questions about build and deployment, check the other documentation sections or contact the development team.

Component Development Analytics Tracking