Documentation System Setup

This guide will walk you through setting up the documentation system for local development and explain how production deployment works.

Overview

The documentation system uses a private Next.js template that contains licensed components. To maintain compliance while keeping the main project open source, we fetch this template during build time rather than committing it to the repository.

Key components:

• Private template: consentdotio/c15t-docs (private repository)
• Local folder: .docs (excluded from workspace and git)
• Unified script: scripts/setup-docs.ts with mode and branch support

Quick Setup

Prerequisites

• Node.js v18 or higher
• pnpm package manager
• GitHub personal access token with read access to private repositories

Development Installation

1. Create your environment file in the project root:

   echo "CONSENT_GIT_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxx" > .env

2. Fetch and setup the documentation:

   pnpm setup:docs

3. Start the development server:

   cd .docs && pnpm dev

4. Open your browser to http://localhost:3000

That's it! The documentation site should now be running locally.

Understanding the Build Modes

Development Mode (Default)

When you run pnpm setup:docs, the script operates in development mode:

• Token source: Loads from your .env file
• Dependencies: Installs only .docs dependencies
• Output: Ready for immediate pnpm dev usage
• Build: Skips production build step

Complete workflow:

1. Validates token from .env file
2. Cleans existing directories
3. Clones private template repository
4. Syncs template to workspace
5. Installs .docs dependencies in isolation

Production Mode (Vercel)

Production builds use the --vercel flag and additional steps:

• Token source: Uses environment variables (Vercel secrets)
• Dependencies: Installs workspace + .docs dependencies
• Output: Optimized production build
• Build: Generates static assets for deployment

Complete workflow:

1. Validates token from environment
2. Cleans existing directories
3. Clones private template repository
4. Syncs template to workspace
5. Installs workspace dependencies
6. Installs .docs dependencies
7. Builds production application

Branch Selection

The fetch script supports different branches of the documentation template:

Available Branches

• main (default) - Stable release branch
• canary - Latest features and updates
• develop - Development branch (if available)

Using Different Branches

# Use default main branch
pnpm setup:docs

# Fetch from canary branch for latest features
pnpm setup:docs -- --branch=canary

# Fetch from development branch
pnpm setup:docs -- --branch=develop

# Production build with specific branch
CONSENT_GIT_TOKEN=xxx tsx scripts/setup-docs.ts --vercel --branch=canary

Note: The double dash (--) is required when passing flags through pnpm scripts.

Available Commands

Authentication Setup

Getting a GitHub Token

1. Go to GitHub Settings > Personal Access Tokens
2. Click "Generate new token" → "Generate new token (classic)"
3. Set an expiration date
4. Select scopes: repo (full repository access)
5. Generate and copy the token

Local Development Setup

Create a .env file in your project root:

# .env file
CONSENT_GIT_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxx

Important: Never commit this file. It's already in .gitignore.

Production Setup (Vercel)

1. Go to your Vercel project dashboard
2. Navigate to Settings → Environment Variables
3. Add CONSENT_GIT_TOKEN with your token value
4. Save and redeploy

File Structure

After running the setup, you'll see these generated files:

scripts/
├── setup-docs.ts           # Unified documentation fetcher
└── README.md               # Technical documentation

Generated during build:
├── .docs/               # Next.js documentation app (gitignored)
│   ├── package.json        # App dependencies
│   ├── next.config.ts      # Next.js configuration
│   └── src/                # Application source code
└── /tmp/new-docs/          # Temporary clone location

Development Workflow

Starting Fresh

# Remove any existing setup
rm -rf .docs

# Fetch and setup everything
pnpm setup:docs

# Start development
cd .docs && pnpm dev

Making Changes

The documentation content lives in the private template repository. For content changes:

1. Make changes in the private consentdotio/c15t-docs repository
2. Re-fetch the template: pnpm setup:docs
3. Restart your dev server: cd .docs && pnpm dev

Working with Components

The template includes pre-built components for documentation. You can:

• Edit existing pages in .docs/src/
• Add new MDX content
• Customize styling and layout
• Test changes locally before deployment

Troubleshooting

Common Issues

Token Authentication Failed

❌ CONSENT_GIT_TOKEN missing. Cannot fetch consentdotio/c15t-docs

Solutions:

• Verify .env file exists in project root
• Check token has read access to private repository
• Ensure token hasn't expired

Development Server Won't Start

Error: Cannot find module 'next'

Solutions:

• Run pnpm setup:docs first to install dependencies
• Ensure you're in the .docs directory when running pnpm dev
• Check that the fetch process completed successfully

Build Failures

💥 development setup failed: Command execution failed

Solutions:

• Check network connectivity
• Verify private repository exists and is accessible
• Review command output for specific error details

Debug Mode

The script automatically shows detailed progress:

🔄 Installing .docs dependencies in isolation...
   Running: pnpm --prefix .docs install --ignore-workspace --frozen-lockfile
✅ Installing .docs dependencies in isolation completed successfully

Clean Reset

If you encounter persistent issues:

# Remove all generated files
rm -rf .docs
rm -rf /tmp/new-docs

# Clear any cached data
pnpm store prune

# Start fresh
pnpm setup:docs

Security Considerations

Why This Approach?

• License Compliance: Private components stay private
• Open Source Friendly: Main codebase remains fully open
• Secure Access: Only authorized users can build documentation
• Vercel Compatible: Works seamlessly with deployment platform

Access Control

• Public forks: Cannot build documentation (no token access)
• Contributors: Need to be granted repository access
• Vercel deployments: Use environment secrets for authentication

Best Practices

• Never commit the .env file or any private content
• Rotate tokens regularly for security
• Use minimal permissions (read-only access to private repository)
• Monitor access logs in GitHub for unauthorized attempts

Production Deployment

Vercel Configuration

When deploying to Vercel, the system automatically:

1. Detects production mode via the --vercel flag
2. Uses environment tokens instead of .env file
3. Installs full workspace dependencies for build context
4. Generates optimized build for fast loading
5. Serves static assets via Vercel's edge network

Build Optimization

The production build includes:

• Static page generation for fast loading
• JavaScript optimization and code splitting
• Asset optimization for images, CSS, and fonts
• SEO metadata generation

Deployment Workflow

1. Push changes to your main repository
2. Vercel detects the push and starts build
3. Script runs tsx scripts/setup-docs.ts --vercel
4. Template fetched using environment token
5. Dependencies installed and app built
6. Static assets deployed to edge network

Next Steps

Once you have the documentation running locally:

• Explore the template structure in .docs/src/
• Review existing documentation to understand the content structure
• Test responsive design across different screen sizes
• Familiarize yourself with the MDX components available
• Check the build process by running a local production build

For questions about the documentation system, check the technical README or reach out to the maintainers.