Skip to main content

​
Build Process

​
Production Build

To create an optimized production build: 
npm run build
This command runs astro build and generates static files in the dist/ directory.

​
Build Configuration

The build process is configured in astro.config.mjs with the following optimizations:

​
Output Mode

output: "static"
The project uses static site generation (SSG). In Astro 5+, static mode allows selective SSR with prerender: false on individual pages.

​
HTML Compression

compressHTML: true
HTML files are automatically minified during build.

​
CSS Optimization

build: {
  inlineStylesheets: "always"
}
  • Stylesheets under 10KB are inlined to reduce render-blocking requests
  • CSS is code-split for better loading performance

​
JavaScript Bundling

vite: {
  build: {
    cssCodeSplit: true,
    minify: "esbuild",
    rollupOptions: {
      output: {
        manualChunks: (id) => {
          if (id.includes("node_modules")) {
            return "vendor";
          }
        }
      }
    }
  }
}
  • esbuild used for fast minification
  • Vendor chunks separated for better caching
  • Dependencies cached independently from application code

​
Build Output

After running npm run build, the dist/ directory contains:
  • Static HTML pages for all routes
  • Optimized CSS and JavaScript bundles
  • Sitemap (sitemap-0.xml, sitemap-index.xml)
  • Assets in _astro/ directory with cache-busting hashes
  • Public assets (favicon, images, etc.)

​
Preview Production Build

Test the production build locally: 
npm run preview
This serves the dist/ directory to verify everything works as expected before deployment.

​
Vercel Deployment

The project is optimized for deployment on Vercel with the @astrojs/vercel adapter.
1
Connect Repository
2
  • Push your code to GitHub, GitLab, or Bitbucket
  • Log in to Vercel
  • Click “Add New” → “Project”
  • Import your repository
    • 3
    Configure Project
    4
  • Framework Preset: Astro (auto-detected)
  • Root Directory: . (default)
  • Build Command: npm run build (auto-detected from package.json)
  • Output Directory: dist (auto-detected)
  • Node.js Version: 18.x or higher
    • 5
    Environment Variables
    6
    If your project requires environment variables:
    7
  • Go to Project Settings → Environment Variables
  • Add your variables (e.g., API keys, configuration)
  • Configure for Production, Preview, and Development as needed
    • 8
    Deploy
    9
  • Click “Deploy”
  • Vercel will build and deploy your site
  • Your site will be available at your-project.vercel.app
    • 10
    Custom Domain
    11
    To use a custom domain (e.g., chapinismos.org):
    12
  • Go to Project Settings → Domains
  • Add your domain
  • Configure DNS records as instructed
  • Vercel handles SSL certificates automatically

    • ​
    Vercel Configuration

    The project includes vercel.json for additional configuration:

    ​
    Security Headers

    All routes include strict security headers:
    • Strict-Transport-Security: Force HTTPS (1 year, including subdomains)
    • X-Frame-Options: DENY (prevent clickjacking)
    • X-Content-Type-Options: nosniff (prevent MIME sniffing)
    • X-XSS-Protection: Enable XSS filtering
    • Referrer-Policy: strict-origin-when-cross-origin
    • Permissions-Policy: Disable geolocation, microphone, camera, payment APIs
    • Content-Security-Policy: Restrict resource loading (allows Umami analytics)

    ​
    Cache Control

    Optimized caching for static assets: 
    {
  "source": "/_astro/:path*",
  "headers": [
    {
      "key": "Cache-Control",
      "value": "public, max-age=31536000, immutable"
    }
  ]
}
    • Astro assets (_astro/*) cached for 1 year (immutable)
    • Favicon cached for 1 year
    • Content-hashed filenames prevent stale caches

    ​
    Redirects

    Language-based redirects configured: 
    {
  "source": "/",
  "has": [
    {
      "type": "header",
      "key": "Accept-Language",
      "value": "es.*"
    }
  ],
  "destination": "/es/",
  "permanent": false
}
    • Root path (/) redirects based on Accept-Language header
    • Spanish users → /es/
    • Others → /en/ (default)

    ​
    Continuous Deployment

    Vercel automatically deploys:
    • Production: Pushes to main branch
    • Preview: Pull requests and other branches
    Each deployment gets:
    • Unique preview URL
    • Automatic SSL certificate
    • Edge network distribution
    • Performance analytics

    ​
    Alternative Deployment Platforms

    While optimized for Vercel, you can deploy to other platforms:

    ​
    Netlify

    1
    Install Netlify Adapter
    2
    npm install @astrojs/netlify
    3
    Update astro.config.mjs
    4
    import netlify from '@astrojs/netlify';

export default defineConfig({
  output: 'static',
  adapter: netlify(),
  // ... rest of config
});
    5
    Deploy
    6
  • Connect repository to Netlify
  • Set build command: npm run build
  • Set publish directory: dist
  • Deploy

    • ​
    Cloudflare Pages

    1
    Install Cloudflare Adapter
    2
    npm install @astrojs/cloudflare
    3
    Update Configuration
    4
    import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  output: 'static',
  adapter: cloudflare(),
  // ... rest of config
});
    5
    Deploy
    6
  • Connect repository to Cloudflare Pages
  • Set build command: npm run build
  • Set output directory: dist
  • Deploy

    • ​
    Static Hosting (Nginx, Apache, etc.)

    For traditional static hosting:
    1. Run npm run build
    2. Upload contents of dist/ to your web server
    3. Configure server for:
      • Trailing slashes (Astro uses trailingSlash: "always")
      • MIME types for .astro extensions (if needed)
      • Proper routing for SPA-like behavior

    ​
    Example Nginx Configuration

    server {
  listen 80;
  server_name chapinismos.org;
  root /var/www/chapinismos/dist;
  index index.html;

  # Ensure trailing slashes
  rewrite ^([^.]*[^/])$ $1/ permanent;

  location / {
    try_files $uri $uri/ $uri/index.html =404;
  }

  # Cache static assets
  location /_astro/ {
    expires 1y;
    add_header Cache-Control "public, immutable";
  }
}

    ​
    Troubleshooting

    ​
    Build Fails

    Check Node.js version: 
    node --version  # Should be >= 18.0.0
    Clear cache and rebuild: 
    rm -rf .astro dist node_modules/.vite
npm run build
    Check for TypeScript errors: Review build output for type checking errors.

    ​
    Deployment Issues

    Vercel build timeout:
    • Check build logs for errors
    • Verify dependencies are in dependencies, not devDependencies
    • Increase build timeout in Vercel project settings if needed
    404 errors after deployment:
    • Verify trailingSlash: "always" is configured
    • Check that routes match expected URL structure
    • Review redirects in vercel.json
    Assets not loading:
    • Ensure site is configured in astro.config.mjs
    • Verify asset paths are relative or use import
    • Check browser console for CORS or CSP errors

    ​
    Performance Issues

    Large bundle size:
    • Analyze with npm run build and check output
    • Consider lazy loading components
    • Review imports for unused dependencies
    Slow page loads:
    • Check Vercel Analytics for performance insights
    • Review Network tab in browser DevTools
    • Verify caching headers are applied correctly

    ​
    Next Steps

    • Monitor deployments in Vercel dashboard
    • Set up Vercel Analytics for performance monitoring
    • Configure custom domains and SSL
    • Review Code Quality for pre-deployment checks

    Build docs developers (and LLMs) love

    Get started for freeTalk to us