This guide walks through setting up your local development environment for our Jamstack projects using Next.js, DatoCMS, and Netlify/Vercel. Following these steps ensures consistency across the team and prevents common setup issues.

• Prerequisites
• Repository Setup
• Environment Variables Configuration
• Installing Dependencies
• DatoCMS Connection
• Running Development Servers
• Verification Steps
• Troubleshooting

Before starting, ensure you have the following installed:

• Node.js: v18.17.0 or higher (check with node -v)
• npm: v9.0.0 or higher (check with npm -v) OR yarn: v1.22.0 or higher
• Git: Latest version
• Code Editor: VS Code (recommended) with team extensions
• DatoCMS Account: Access to the project workspace

• nvm or fnm for Node version management
• Git GUI client (optional)

# Using SSH (recommended)
git clone [email protected]:your-org/project-name.git

# Using HTTPS
git clone https://github.com/your-org/project-name.git

# Navigate to project directory
cd project-name

# Check current branch
git branch

# Switch to development branch
git checkout develop

# Copy the example environment file
cp .env.example .env.local

Your .env.local file should include:

# DatoCMS Configuration
NEXT_PUBLIC_DATOCMS_API_TOKEN=your-read-only-api-token
DATOCMS_PREVIEW_SECRET=your-preview-secret
DATOCMS_API_TOKEN=your-full-access-token
NEXT_PUBLIC_DATOCMS_ENVIRONMENT=main

# Next.js Configuration
NEXT_PUBLIC_SITE_URL=http://localhost:3000

# Deployment Platform (if needed locally)
NETLIFY_SITE_ID=your-site-id
VERCEL_PROJECT_ID=your-project-id

# Additional Services (as needed)
NEXT_PUBLIC_GTM_ID=your-gtm-id
SMTP_HOST=your-smtp-host
SMTP_PORT=587

1. Log in to DatoCMS
2. Navigate to your project
3. Go to Settings → API Tokens
4. Create/copy the following tokens:
   • Read-only API Token: For public content fetching
   • Full-access API Token: For preview mode and migrations
   • Preview Secret: Random string for securing preview routes

Document where to obtain other API keys your project uses.

⚠️ Important Security Notes:

• Never commit .env.local to version control
• .env.local should be in .gitignore
• Use different tokens for development and production
• Rotate tokens regularly
• Store production secrets in Netlify/Vercel dashboard

# Install all dependencies
npm install

# Install with clean slate (if having issues)
rm -rf node_modules package-lock.json
npm install

# Install all dependencies
yarn install

# Install with clean slate (if having issues)
rm -rf node_modules yarn.lock
yarn install

If you encounter permission errors:

# Clear npm cache
npm cache clean --force

# Use node version specified in .nvmrc
nvm use

Ensure you're connecting to the correct DatoCMS environment:

// lib/datocms.js - verify this configuration
const client = new GraphQLClient('https://graphql.datocms.com/', {
  headers: {
    authorization: `Bearer ${process.env.DATOCMS_API_TOKEN}`,
    'X-Environment': process.env.NEXT_PUBLIC_DATOCMS_ENVIRONMENT || 'main',
  },
});

Create a test script scripts/test-datocms.js:

require('dotenv').config({ path: '.env.local' });

async function testConnection() {
  try {
    const response = await fetch('https://graphql.datocms.com/', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${process.env.DATOCMS_API_TOKEN}`,
        'X-Environment': process.env.NEXT_PUBLIC_DATOCMS_ENVIRONMENT || 'main',
      },
      body: JSON.stringify({
        query: `{ _site { globalSeo { siteName } } }`
      }),
    });
    
    const data = await response.json();
    console.log('✅ DatoCMS Connection Successful:', data);
  } catch (error) {
    console.error('❌ DatoCMS Connection Failed:', error);
  }
}

testConnection();

Run with: node scripts/test-datocms.js

For Next.js preview mode with DatoCMS:

1. Ensure preview API route exists at pages/api/preview.js or app/api/preview/route.js
2. Configure preview URL in DatoCMS:
   • Go to Settings → Webhooks
   • Set preview URL: https://your-site.com/api/preview?secret=YOUR_SECRET&slug={slug}

# Using npm
npm run dev

# Using yarn
yarn dev

# With specific port
npm run dev -- -p 3001

Standard scripts in package.json:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "test": "jest",
    "type-check": "tsc --noEmit"
  }
}

Once running, you'll have access to:

• Application: http://localhost:3000
• Fast Refresh: Automatic page updates on save
• Error Overlay: Detailed error messages in browser
• API Routes: http://localhost:3000/api/*

Run through these checks to ensure proper setup:

npm run build

✅ Build completes without errors

npm run type-check

✅ No TypeScript errors

npm run lint

✅ No linting errors

• Navigate to a page that fetches DatoCMS content
• ✅ Content loads properly
• ✅ Images from DatoCMS display correctly

• Access /api/preview?secret=YOUR_SECRET&slug=/
• ✅ Preview bar appears
• ✅ Draft content is visible

# Find process using port 3000
lsof -i :3000

# Kill the process
kill -9 <PID>

• Verify API token is correct and active
• Check environment variable names match exactly
• Ensure you're using the correct environment (main/development)

# Clear cache and reinstall
rm -rf node_modules .next
npm install
npm run dev

• Ensure .env.local is in project root
• Restart dev server after changing env vars
• Check for typos in variable names

If you encounter issues not covered here:

1. Check project-specific README
2. Search team documentation
3. Ask in #dev-help Slack channel
4. Create a GitHub issue with details

• Project Initialization
• DatoCMS Setup
• Common Commands
• Troubleshooting Guide

June 9, 2025 - Initial setup guide created