Cascadia Marquee
Discuss a Project

Development Setup Guide

Complete guide to setting up the Cascadia Marquee website development environment

Development Setup Guide

Complete guide to setting up the Cascadia Marquee website development environment.

Prerequisites

  • Node.js 18+ - Download from nodejs.org
  • pnpm (recommended) or npm/yarn - Install with npm install -g pnpm
  • Git - For version control

Installation

1. Clone the Repository

git clone <repository-url>
cd cascadia-marquee_website

2. Install Dependencies

pnpm install

3. Environment Variables

Create a .env.local file in the root directory:

cp .env.local.example .env.local

Required environment variables:

# Canonical app URL (OAuth callbacks use APP_URL + fixed paths)
APP_URL=http://localhost:3000
NEXT_PUBLIC_APP_URL=http://localhost:3000
 
# 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 (production / optional for local testing with next start)
NEXT_PUBLIC_GA_MEASUREMENT_ID=G-XXXXXXXXXX
NEXT_PUBLIC_CLARITY_PROJECT_ID=
 
# Facebook Pixel
FACEBOOK_PIXEL_ID=your_pixel_id

4. Run Development Server

pnpm dev

The site will be available at http://localhost:3000

Development Commands

Core Commands

# Start development server
pnpm dev
 
# Build for production
pnpm build
 
# Start production server
pnpm start
 
# Type check
pnpm type-check

Content and registry

# Build component registry (MDX docs use Content Collections via next dev / next build)
pnpm build:registry
 
# Regenerate navigation from content folders
pnpm build:navigation

Code Quality

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

Development Workflow

1. Content Development

  • Blog Posts: Add .mdx files to src/content/posts/
  • Documentation: Add .mdx files to src/content/docs/
  • Services: Add .mdx files to src/content/services/

2. Component Development

  • UI Components: Use shadcn/ui or create custom components in src/components/ui/
  • Layout Components: Add to src/components/layout/
  • Feature Components: Add to appropriate subdirectories

3. Styling

  • Tailwind CSS: Use utility classes for styling
  • Custom CSS: Add to src/app/globals.css
  • Component Styles: Use CSS modules or styled-components

Project Structure Deep Dive

App Router Structure

src/app/
├── api/                    # API routes
│   ├── debug/             # Debug endpoints
│   ├── emails/            # Email handling
│   └── google-calendar/   # Calendar integration
├── blog/                  # Blog pages
│   ├── [[...slug]]/      # Dynamic blog post routes
│   ├── [category]/       # Category pages
│   └── tags/             # Tag pages
├── contact/               # Contact page
├── docs/                  # Documentation
│   └── [[...slug]]/      # Dynamic doc routes
├── legal/                 # Legal pages
├── services/              # Service pages
└── layout.tsx             # Root layout

Component Architecture

src/components/
├── ui/                    # shadcn/ui components
├── layout/                # Layout components
│   ├── layouts/           # Page layouts
│   ├── partials/          # Header, footer, etc.
│   └── sections/          # Page sections
├── contact/               # Contact form components
├── charts/                # Data visualization
├── icons/                 # Custom icons
└── text/                  # Typography components

Content Management

src/content/
├── docs/                  # Documentation content
│   ├── 1_guides/         # Technical guides
│   └── 2_documentation/  # Project documentation
├── posts/                 # Blog posts
│   ├── case-studies/     # Client case studies
│   ├── posts/            # General blog posts
│   └── tutorials/        # Tutorial content
├── services/              # Service descriptions
└── legal/                 # Legal documents

Configuration Files

Next.js Configuration (next.config.ts)

import { withContentCollections } from "@content-collections/next";
 
const nextConfig = {
  pageExtensions: ["js", "jsx", "ts", "tsx", "md", "mdx"],
  images: {
    remotePatterns: [
      {
        protocol: "https" as const,
        hostname: "images.unsplash.com",
      },
    ],
  },
  turbopack: {
    root: process.cwd(),
    resolveAlias: {
      process: "process/browser",
    },
  },
};
 
// Content Collections must wrap the config so MDX is built with Next.js.
export default withContentCollections(nextConfig);

Tailwind Configuration (tailwind.config.ts)

import type { Config } from "tailwindcss";
 
export default {
  darkMode: ["class"],
  content: [
    "./src/pages/**/*.{js,ts,jsx,tsx,mdx}",
    "./src/components/**/*.{js,ts,jsx,tsx,mdx}",
    "./src/app/**/*.{js,ts,jsx,tsx,mdx}",
  ],
  theme: {
    extend: {
      colors: {
        background: "hsl(var(--background))",
        foreground: "hsl(var(--foreground))",
        // ... more color definitions
      },
    },
  },
  plugins: [require("tailwindcss-animate")],
} satisfies Config;

Content Collections (content-collections.ts)

The root content-collections.ts file defines four collections (Zod schemas plus transforms):

  • docs (Doc, allDocs) - Documentation pages
  • posts (Post, allPosts) - Blog posts
  • legalDocs (LegalDoc, allLegalDocs) - Legal documents
  • services (Service, allServices) - Service descriptions

MDX is compiled at build/dev time. Import collections in app code:

import { allPosts } from "content-collections";

Generated types and data live in .content-collections/generated (gitignored). tsconfig.json maps content-collections to that folder.

Development Tools

ESLint Configuration

The project uses a custom ESLint configuration with:

  • Import ordering - Automatic import sorting
  • TypeScript rules - Type checking and best practices
  • React rules - React-specific linting
  • Prettier integration - Code formatting

TypeScript Configuration

  • Strict mode enabled
  • Path mapping for clean imports (@/ aliases)
  • Next.js types included
  • Content Collections types generated automatically in .content-collections/generated

Troubleshooting

Common Issues

"Module not found" errors:

  • Run pnpm install to ensure all dependencies are installed
  • Check that file paths are correct
  • Verify TypeScript path mappings

Content not updating:

  • Restart pnpm dev or run pnpm build (Content Collections runs with Next.js)
  • Check that MDX files have proper front matter
  • Verify file naming conventions

Build errors:

  • Run pnpm type-check to identify TypeScript errors
  • Check ESLint output with pnpm lint
  • Verify environment variables are set

Styling issues:

  • Ensure Tailwind classes are properly configured
  • Check that CSS variables are defined
  • Verify component imports

Performance Optimization

  • Image optimization - Use next/image for all images
  • Font optimization - Use next/font for custom fonts
  • Code splitting - Leverage Next.js automatic code splitting
  • Bundle analysis - Use @next/bundle-analyzer for optimization

Next Steps

  1. Set up your development environment following this guide
  2. Explore the content structure in src/content/
  3. Check out the component library in src/components/ui/
  4. Review the technical guides in the documentation section
  5. Start contributing to the project!

For questions or help, check the other documentation sections or contact the development team.

Content Management