Vercel Deployment - Ayuntamiento de Zongolica

Overview

Vercel is the recommended hosting platform for the Ayuntamiento de Zongolica application. This guide walks you through deploying your Astro application with the Vercel adapter.

Prerequisites

Before deploying, ensure you have:

A GitHub account with your code repository
A Vercel account (free tier available)
Completed Supabase setup
Your environment variables ready

Project Configuration

The application is already configured for Vercel deployment:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';
import react from '@astrojs/react';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  output: 'server',
  adapter: vercel(),
  vite: {
    plugins: [tailwindcss()]
  },
  i18n: {
    locales: ["es", "en", "nah-MX"],
    defaultLocale: "es",
    routing: {
      prefixDefaultLocale: false,
    },
  },
  integrations: [react()]
});

The output: 'server' configuration enables SSR (Server-Side Rendering), which is required for authentication and dynamic content.

Deploy from GitHub

Push Code to GitHub

Ensure your code is pushed to a GitHub repository:

git add .
git commit -m "Ready for deployment"
git push origin main

Connect to Vercel

Go to vercel.com and sign in
Click Add New → Project
Import your GitHub repository

Configure Build Settings

Vercel should auto-detect Astro. Verify these settings:

Framework Preset: Astro
Build Command: astro build (or npm run build)
Output Directory: dist
Install Command: npm install

Add Environment Variables

Click Environment Variables and add:

PUBLIC_SUPABASE_URL=https://your-project.supabase.co
PUBLIC_SUPABASE_ANON_KEY=your-anon-key

Add any other optional variables your application needs.

Deploy

Click Deploy and wait for the build to complete (usually 1-2 minutes)

Deploy Configuration

The application includes a vercel.json file for advanced configuration:

URL Redirects

Configured redirects for legacy URLs and route corrections:

{
  "redirects": [
    { 
      "source": "/xochitlanis", 
      "destination": "/xochitlallis", 
      "permanent": true 
    },
    { 
      "source": "/portal/:path*", 
      "destination": "/", 
      "permanent": true 
    }
  ]
}

These redirects maintain SEO value from old URLs and ensure visitors reach the correct pages.

Cache Headers

Optimized caching for static assets:

{
  "headers": [
    {
      "source": "/_astro/(.*)",
      "headers": [
        { 
          "key": "Cache-Control", 
          "value": "public, max-age=31536000, immutable" 
        }
      ]
    }
  ]
}

This configuration:

Caches Astro-generated assets for 1 year
Marks them as immutable for maximum efficiency
Reduces bandwidth and improves load times

Custom Domain Setup

Add Domain in Vercel

Go to your project Settings → Domains
Click Add Domain
Enter your domain (e.g., zongolica.gob.mx)

Configure DNS Records

Add these DNS records in your domain registrar:Option A: Using Vercel nameservers (Recommended)

Update your domain’s nameservers to Vercel’s

Option B: Using A/CNAME records

Type: A
Name: @
Value: 76.76.21.21

Type: CNAME
Name: www
Value: cname.vercel-dns.com

Update Supabase URLs

Update redirect URLs in Supabase:

Go to Authentication → URL Configuration
Update Site URL: https://your-domain.com
Add to Redirect URLs: https://your-domain.com/auth/callback

Verify SSL Certificate

Vercel automatically provisions SSL certificates. Wait a few minutes for it to activate.

Multi-Language Routes

The application supports three locales:

es (Spanish - default): https://your-domain.com/turismo
en (English): https://your-domain.com/en/tourism
nah-MX (Nahuatl): https://your-domain.com/nah-MX/turismo

The default locale (es) doesn’t include a prefix in the URL, following the prefixDefaultLocale: false configuration.

Continuous Deployment

Vercel automatically deploys when you push to GitHub:

# Make changes
git add .
git commit -m "Update content"
git push origin main

# Vercel automatically builds and deploys

Deployment Branches

Production: Deploys from main branch
Preview: Automatically created for pull requests
Development: You can configure additional branches

Environment-Specific Variables

Set different values for different environments:

Go to Environment Variables

In Vercel project settings, click Environment Variables

Add Variable

When adding a variable, select which environments should use it:

Production: Live site
Preview: Pull request previews
Development: Local development (optional)

Use Different Values

You can set different values for each environment, useful for:

Using a development Supabase project for previews
Disabling analytics in preview environments
Testing with sandbox API credentials

Monitoring and Analytics

View Deployment Logs

Access Logs

Go to your project → Deployments → Click on a deployment

Check Build Logs

Review the Building section for build-time errors

Check Runtime Logs

Click Runtime Logs to see server-side errors

Enable Vercel Analytics

Install Package

npm install @vercel/analytics

Add to Layout

---
// src/layouts/Layout.astro
import { inject } from '@vercel/analytics';
inject();
---

Enable in Dashboard

Go to your project settings → Analytics → Enable

Troubleshooting

Build Fails

Check build logs for specific errors:

# Common issues:
- Missing environment variables
- TypeScript errors
- Import path issues

Solution: Fix the error locally first:

npm run build

404 Errors After Deploy

Possible causes:

SSR routes not configured properly
Missing pages

Solution: Verify output: 'server' in astro.config.mjs

Environment Variables Not Working

Verify variable names match exactly (case-sensitive)
Check if variables need PUBLIC_ prefix
Redeploy after adding/changing variables
Clear cache and redeploy if needed

Slow Build Times

Optimize build:

Remove unused dependencies
Use Vercel’s build cache
Optimize images before uploading

Vercel CLI (Optional)

For advanced users, deploy from the command line:

Install Vercel CLI

npm install -g vercel

vercel login

Deploy

# Deploy to preview
vercel

# Deploy to production
vercel --prod

Best Practices

✅ Recommended:

Use environment-specific variables
Enable automatic deployments from main branch
Set up preview deployments for pull requests
Monitor build times and optimize as needed
Use custom domains with SSL
Enable Vercel Analytics for insights

❌ Avoid:

Committing .env files
Using production credentials in preview environments
Deploying without testing locally first
Ignoring build warnings

Next Steps

After deploying to Vercel:

Configure OAuth providers with your production URL
Set up storage buckets in Supabase
Test authentication flow on your live site
Configure your custom domain

Setup

Configuration

Documentation Index

​Overview

​Prerequisites

​Project Configuration

​Deploy from GitHub

​Deploy Configuration

​URL Redirects

​Cache Headers

​Custom Domain Setup

​Multi-Language Routes

​Continuous Deployment

​Deployment Branches

​Environment-Specific Variables

​Monitoring and Analytics

​View Deployment Logs

​Enable Vercel Analytics

​Troubleshooting

​Build Fails

​404 Errors After Deploy

​Environment Variables Not Working

​Slow Build Times

​Vercel CLI (Optional)

​Best Practices

​Next Steps

Build docs developers (and LLMs) love

Overview

Prerequisites

Project Configuration

Deploy from GitHub

Deploy Configuration

URL Redirects

Cache Headers

Custom Domain Setup

Multi-Language Routes

Continuous Deployment

Deployment Branches

Environment-Specific Variables

Monitoring and Analytics

View Deployment Logs

Enable Vercel Analytics

Troubleshooting

Build Fails

404 Errors After Deploy

Environment Variables Not Working

Slow Build Times

Vercel CLI (Optional)

Best Practices

Next Steps