Skip to main content
This website is deployed on Vercel, which provides automatic deployments from your GitHub repository with zero configuration needed for Astro projects.

​
Configuration

The project includes a vercel.json configuration file:
vercel.json
{
  "cleanUrls": true,
  "headers": [
    {
      "source": "/fonts/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "max-age=15552000, public, immutable"
        }
      ]
    }
  ]
}

​
Configuration Options

​
cleanUrls
boolean
default:"true"
Removes .html extensions from URLs. For example, /blog.html becomes /blog.
​
headers
array
Custom HTTP headers for specific routes. Used here to cache fonts for 180 days.

​
Deployment Process

1

Connect Repository

Connect your GitHub repository to Vercel:
  1. Go to vercel.com
  2. Click “Add New” → “Project”
  3. Import your website-astro repository
  4. Vercel auto-detects Astro framework
2

Configure Environment Variables

Add all required environment variables in the Vercel dashboard:Project Settings → Environment VariablesRequired variables:
  • NOTION_TOKEN
  • NOTION_BLOG_DB_ID
  • NOTION_PROJECTS_DB_ID
  • All other NOTION_PAGE_ID_* and NOTION_DB_ID_* variables
Environment variables are encrypted and securely stored. They’re available during build time for the Notion sync process.
3

Configure Build Settings

Vercel automatically detects the correct settings:
  • Framework: Astro
  • Build Command: pnpm build
  • Output Directory: dist
  • Install Command: pnpm install
The prebuild script in package.json runs automatically before the build, syncing content from Notion.
4

Deploy

Click “Deploy” and Vercel will:
  1. Install dependencies with pnpm
  2. Run the prebuild script (Notion sync)
  3. Build the static site
  4. Deploy to global edge network
  5. Assign a production URL

​
Deployment Types

Production deployments occur automatically when you push to the main branch:
git push origin main
Features:
  • Deployed to production domain
  • Full Notion content sync
  • Automatic cache invalidation
  • SSL certificate
  • Global CDN distribution

​
Build Time

Initial Build

3-5 minutes
  • Install dependencies: ~1-2 min
  • Notion sync: ~30-60 sec
  • Astro build: ~1-2 min
  • Deploy: ~30 sec

Incremental Build

2-3 minutes
  • Cached dependencies: ~30 sec
  • Incremental sync: ~10-20 sec
  • Astro build: ~1-2 min
  • Deploy: ~30 sec

​
Environment-Specific Behavior

// Notion sync only runs at build time
if (import.meta.env.NODE_ENV === 'production') {
  // All data is pre-fetched and static
  // No runtime API calls to Notion
}
The website makes zero runtime API calls to Notion. All content is fetched at build time and served as static HTML.

​
Triggering Rebuilds

To update content from Notion:
In the Vercel dashboard:
  1. Go to Deployments
  2. Click the three dots on any deployment
  3. Select Redeploy
This re-runs the full build process, syncing fresh content from Notion.
Create a Deploy Hook for automated rebuilds:
  1. Go to Project Settings → Git
  2. Scroll to Deploy Hooks
  3. Create a hook named “Notion Content Update”
  4. Copy the webhook URL
Trigger rebuilds programmatically:
curl -X POST https://api.vercel.com/v1/integrations/deploy/...
Make any commit to the main branch:
git commit --allow-empty -m "Trigger rebuild"
git push origin main

​
Performance Optimizations

Vercel automatically applies:
  • Edge caching: Static assets cached globally
  • Brotli compression: Smaller transfer sizes
  • HTTP/3 support: Faster connections
  • Image optimization: Automatic WebP/AVIF conversion (via Astro)
  • Smart CDN: Content served from nearest edge location

​
Custom Font Caching

Fonts are cached for 180 days (configured in vercel.json): 
Cache-Control: max-age=15552000, public, immutable
This means variable fonts (Inter, Newsreader) load instantly on repeat visits.

​
Monitoring

​
Analytics

Vercel provides built-in analytics:
  • Page views and unique visitors
  • Top pages and referrers
  • Core Web Vitals (LCP, FID, CLS)
  • Geographic distribution

​
Build Logs

Access detailed build logs in the dashboard:
  1. Go to Deployments
  2. Click any deployment
  3. View Build Logs tab
Logs include:
  • Notion sync output
  • Build warnings/errors
  • Deployment status

​
Troubleshooting

Solution: Add environment variables in Vercel dashboard.Go to Project Settings → Environment Variables and add all required Notion variables.
Solution: Trigger a manual redeploy.Changes in Notion only appear after a rebuild. Use any of the three rebuild methods above.
Solution: Check Notion sync performance.Review build logs to see how long the Notion sync takes. If it’s slow:
  • Check if you have many unchanged posts (should use incremental sync)
  • Verify Notion API response times
  • Consider reducing the number of posts/projects
Solution: Verify image paths and Notion downloads.Images from Notion are downloaded to public/ during build. Check:
  • Build logs for asset download errors
  • Image URLs in generated MDX files
  • Public directory in deployment

​
Next Steps

Build Process

Learn about the full build pipeline

Local Setup

Set up local development environment

Build docs developers (and LLMs) love

Get started for freeTalk to us