Development Guide

Development Guide

This guide provides comprehensive instructions for setting up the development environment, running the project locally, and contributing to the 8531 TeamSite.

🏗️ Project Structure

/srv/team.8531.ca/
├── .dev/                           # Development documentation
├── src/
│   ├── components/                 # Astro components
│   │   ├── AuthButton.astro       # Authentication UI component
│   │   └── GoogleDriveFolder.astro # Reusable Google Drive folder display
│   ├── content/                   # Documentation content
│   │   ├── docs/                  # All documentation pages
│   │   │   ├── public/           # Publicly accessible content
│   │   │   ├── protected/        # Member+ restricted content
│   │   │   └── admin/            # Admin only content
│   │   └── config.ts             # Content schema and configuration
│   ├── lib/                      # Core utilities and services
│   │   ├── auth.ts               # JWT verification and auth utilities
│   │   ├── auth-client.ts        # Client-side authentication helpers
│   │   ├── config.ts             # Environment detection and configuration
│   │   ├── nav.ts                # Navigation generation
│   │   ├── google-drive.ts       # Google Drive integration service
│   │   ├── folder-utils.ts       # Folder utility functions
│   │   └── README-google-drive.md # Google Drive documentation
│   ├── data/                     # Data and configuration
│   │   └── pdfs.ts               # PDF metadata management
│   ├── pages/                    # Astro pages and API routes
│   │   ├── api/
│   │   │   ├── auth/
│   │   │   │   ├── login.ts      # OAuth login endpoint
│   │   │   │   ├── callback.ts   # OAuth callback handler
│   │   │   │   └── logout.ts     # Logout endpoint
│   │   │   ├── pdfs-dev/         # PDF file access endpoints
│   │   │   │   ├── index.ts      # PDF listing and search
│   │   │   │   └── [fileId].ts   # PDF download endpoint
│   │   │   └── test/             # Testing endpoints
│   │   │       └── drive-test.ts # Google Drive testing
│   │   ├── session.ts            # Session verification endpoint
│   │   └── index.astro           # Homepage
│   ├── layouts/Layout.astro      # Main site layout
│   ├── route-middleware.ts       # Authentication middleware
│   └── styles/global.css         # Global styles
├── astro.config.mjs              # Astro configuration
├── package.json                  # Dependencies and scripts
├── vercel.json                   # Deployment configuration
├── .env.example                  # Environment variables template
└── README.md                     # Main project README

🛠️ Technology Stack

• Framework: Astro 5.15.3 with Starlight
• Styling: Tailwind CSS 4.1.16
• Authentication: JWT with RS256 encryption
• File Storage: Google Drive API v3
• Deployment: Vercel with serverless functions
• Content: Markdown-based with frontmatter
• Language: TypeScript

📦 Installation & Setup

Prerequisites

• Node.js 18+ (recommend using Node.js 20+)
• npm or yarn package manager
• Git

Quick Start

1. Clone the repository

   git clone <repository-url>
   cd team.8531.ca

2. Install dependencies

   npm install

3. Set up environment variables

   cp .env.example .env.local

4. Configure environment variables Edit .env.local with your configuration (see Environment Configuration)

5. Start development server

   npm run dev

6. Open your browser Navigate to http://localhost:4321

🧞 Development Commands

Command	Action
npm install	Install dependencies
npm run dev	Start local development server at localhost:4321
npm run build	Build production site to ./dist/
npm run preview	Preview build locally before deployment
npm run astro	Run Astro CLI commands

Development Server Options

The development server supports additional options:

# Start on specific port
npm run dev -- --port 4322

# Start with specific host
npm run dev -- --host 0.0.0.0

# Open browser automatically
npm run dev -- --open

🔧 Environment Configuration

Required Environment Variables

Create a .env.local file with the following variables:

# Site Configuration
NODE_ENV=development
SITE_URL=http://localhost:4321

# Authentication
AUTH_GATEWAY_URL=https://auth.8531.ca
JWT_SECRET=your-jwt-secret-that-is-at-least-32-characters-long
JWT_ISSUER=https://auth.8531.ca
JWT_AUDIENCE=8531-apps

# Google Drive (optional - see Google Drive Integration guide)
GOOGLE_SERVICE_ACCOUNT_EMAIL=[email protected]
GOOGLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nYour-private-key\n-----END PRIVATE KEY-----"

Environment-Specific Settings

The application automatically detects its environment:

Development (NODE_ENV=development)

• Detailed error messages
• Source maps enabled
• Authentication testing modes available
• Live reload enabled

Production (NODE_ENV=production)

• Optimized build
• Minified assets
• Production authentication flows
• Error reporting simplified

Testing (NODE_ENV=test)

• Test-specific configurations
• Mock authentication available
• Database connections disabled

🧪 Testing

Local Testing

Testing Authentication

Test different user roles with query parameters:

# Test as Guest (default)
http://localhost:4321

# Test as Member
http://localhost:4321?test_role=Member

# Test as Core Team
http://localhost:4321?test_role=CoreTeam

# Test as Admin
http://localhost:4321?test_role=Admin

Testing Content Status

Test content visibility with status overrides:

# Show all content regardless of status
http://localhost:4321?show_status=true

# Combine role and status testing
http://localhost:4321?test_role=CoreTeam&show_status=true

Testing Google Drive Integration

# Test Google Drive connection
curl "http://localhost:4321/api/test/drive-test?action=list"

# Test file access
curl "http://localhost:4321/api/test/drive-test?action=download&fileId=YOUR_FILE_ID"

Component Testing

When creating new components:

1. Create test pages in development directories
2. Test with different authentication states
3. Verify responsive design
4. Check accessibility features

API Testing

Use tools like curl or Postman to test API endpoints:

# Test authentication endpoint
curl -X GET "http://localhost:4321/api/auth/login"

# Test session verification
curl -X GET "http://localhost:4321/api/session"

# Test PDF endpoint with folder
curl "http://localhost:4321/api/pdfs-dev?folderId=YOUR_FOLDER_ID"

🎨 Working with Styles

Global Styles

Global styles are defined in src/styles/global.css:

• CSS custom properties (variables)
• Base styles
• Utility classes

Component Styles

Components can include scoped styles:

---
// Your component logic here
---

<style>
  .my-component {
    color: var(--sl-color-text);
  }
</style>

Tailwind CSS

Tailwind is configured with:

• Custom color scheme matching Starlight
• Responsive utilities
• Dark mode support

🔌 Adding New Features

Creating API Endpoints

1. Create a new file in src/pages/api/
2. Export a GET (or other HTTP method) function
3. Handle authentication if needed
4. Return proper responses

Example:

src/pages/api/new-feature.ts

import type { APIRoute } from 'astro';

export const GET: APIRoute = async ({ request }) => {
  // Your API logic here
  return new Response(JSON.stringify({ success: true }), {
    status: 200,
    headers: { 'Content-Type': 'application/json' }
  });
};

Creating Components

1. Create .astro files in src/components/
2. Use TypeScript for type safety
3. Include props validation when needed
4. Add responsive design

Example:

---
export interface Props {
  title: string;
  subtitle?: string;
}

const { title, subtitle } = Astro.props;
---

<div class="my-component">
  <h1>{title}</h1>
  {subtitle && <p>{subtitle}</p>}
  <slot />
</div>

<style>
  .my-component {
    padding: 1rem;
    border: 1px solid var(--sl-color-gray-6);
    border-radius: 8px;
  }
</style>

Adding Content

1. Create .md files in appropriate content directories
2. Include proper frontmatter
3. Follow the content creation workflow
4. Test with different roles

🔄 Hot Module Replacement

The development server supports:

• Live reload for file changes
• Hot module replacement for styles
• Fast refresh for components
• Content updates without full page reload

🐛 Debugging

Common Issues

1. Port Already in Use

   # Find process using port 4321
   lsof -ti:4321
   # Kill the process
   kill -9 $(lsof -ti:4321)
   # Or use different port
   npm run dev -- --port 4322

2. Authentication Not Working

   • Check environment variables
   • Verify AUTH_GATEWAY_URL is correct
   • Check browser console for errors

3. Build Errors

   • Check TypeScript errors
   • Verify all dependencies are installed
   • Clean and reinstall if needed

4. Content Not Showing

   • Verify file permissions (644)
   • Check frontmatter syntax
   • Test with different roles

Debug Mode

Enable debug logging:

# Set debug environment variable
DEBUG=* npm run dev

Browser DevTools

Use browser developer tools to:

• Inspect network requests
• Check console for errors
• Examine local storage/cookies
• Debug JavaScript issues

📝 Code Style Guide

TypeScript

• Use TypeScript for all new code
• Define interfaces for complex objects
• Use proper typing for functions
• Enable strict mode in tsconfig.json

Astro

• Use .astro for components
• Keep logic in the frontmatter
• Use slots for flexible content
• Follow Astro best practices

Markdown

• Use standard Markdown syntax
• Include proper frontmatter
• Use relative links for internal content
• Add alt text for images

🤝 Contributing

Before Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Code Review Process

1. All changes require review
2. Automated tests must pass
3. Documentation must be updated
4. Follow coding standards
5. Test with different user roles

Commit Messages

Use conventional commit messages:

• feat: for new features
• fix: for bug fixes
• docs: for documentation
• refactor: for code refactoring
• test: for adding tests
• chore: for maintenance

📚 Additional Resources

Documentation

• Astro Documentation
• Starlight Documentation
• TypeScript Handbook

Tools

• VS Code Extensions
  • Astro
  • Tailwind CSS IntelliSense
  • TypeScript Importer
  • Markdown All in One

Helpful Scripts

Create custom npm scripts in package.json:

{
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "clean": "rm -rf dist node_modules/.astro",
    "type-check": "tsc --noEmit",
    "lint": "eslint src --ext .ts,.astro",
    "format": "prettier --write src/**/*.{ts,astro,md}"
  }
}

🚀 Deployment

Building for Production

# Build optimized version
npm run build

# Preview before deployment
npm run preview

Vercel Deployment

The project is configured for Vercel deployment:

1. Connect repository to Vercel
2. Configure environment variables
3. Automatic deployment on push to main branch
4. Preview deployments for pull requests

Environment Variables for Production

Configure these in Vercel:

• NODE_ENV=production
• SITE_URL=https://team.8531.ca
• AUTH_GATEWAY_URL=https://auth.8531.ca
• JWT_SECRET (generate a secure random string)
• All Google Drive variables if using file storage