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 Management

# Build content (MDX processing)
pnpm build:content
 
# Build component registry
pnpm build:registry

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 { withContentlayer } from "next-contentlayer2";
 
const nextConfig = {
  pageExtensions: ["js", "jsx", "ts", "tsx", "md", "mdx"],
  images: {
    remotePatterns: [
      {
        protocol: "https" as const,
        hostname: "images.unsplash.com",
      },
    ],
  },
  eslint: {
    ignoreDuringBuilds: true,
  },
  webpack: (config) => {
    config.resolve.fallback = {
      ...config.resolve.fallback,
      process: require.resolve("process/browser"),
    };
    return config;
  },
};
 
export default withContentlayer(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;

Contentlayer Configuration (contentlayer.config.ts)

The contentlayer configuration defines document types for:
  • Doc - Documentation pages
  • Post - Blog posts
  • LegalDoc - Legal documents
  • Service - Service descriptions

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
  • Contentlayer types generated automatically

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:
  • Run pnpm build:content to rebuild content
  • 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.
Next.js 15 & TypeScript GuideContent Management