Configuring Vercel for Hugo and Eleventy

Vercel is best known for Next.js, but it deploys any static site generator, and Hugo and Eleventy work well there with a little configuration. The defaults get a site online quickly, yet they differ from what these generators expect in a few places — the Hugo version on the build image, trailing slash handling, where redirects and headers live — and those differences show up as broken themes, duplicate URLs or missing security headers after launch.

This guide configures a Hugo site and an Eleventy site on Vercel for production: pinned versions, build commands and output directories, clean URLs and trailing slashes, headers, redirects and caching, all in vercel.json so the setup is versioned with the code. It is part of Netlify vs Vercel Deployment Strategies.

Prerequisites

A Hugo or Eleventy site in a Git repository connected to a Vercel project.
The Vercel CLI for local checks: npm install -D vercel.
Knowledge of the canonical URL form your site uses — with or without trailing slashes.

Build Settings

Vercel detects both generators and applies a framework preset. Make the important settings explicit in vercel.json so they do not depend on dashboard state:

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "framework": "hugo",
  "buildCommand": "hugo --gc --minify",
  "outputDirectory": "public",
  "build": {
    "env": { "HUGO_VERSION": "0.134.0", "HUGO_ENV": "production" }
  }
}

For Eleventy:

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "framework": "eleventy",
  "installCommand": "npm ci",
  "buildCommand": "npx @11ty/eleventy",
  "outputDirectory": "_site"
}

The single most important line for Hugo is HUGO_VERSION. Vercel's build image ships an older Hugo by default, and many themes require recent features; an unpinned build can fail or, worse, succeed with different output than your local machine. Use the extended edition if your theme compiles Sass. For Eleventy, pin Node with an engines field in package.json or .nvmrc.

Put every setting in vercel.json so a new project or a teammate gets the same result.

Clean URLs and Trailing Slashes

Hugo and Eleventy both write pages as folder/index.html and link to them as /folder/. Vercel's defaults serve /folder/index.html at /folder/ but also at /folder, creating two URLs for each page. Tell Vercel which form is canonical:

{
  "cleanUrls": true,
  "trailingSlash": true
}

With trailingSlash: true, /docs/install redirects with a 308 to /docs/install/, matching the generator's links and canonical tags. cleanUrls: true removes .html from any flat files and redirects /about.html to /about/. If your Hugo config uses uglyURLs or your Eleventy permalinks end in .html, set trailingSlash: false instead and be consistent. Mismatched settings are a common source of duplicate URLs in Search Console.

A one-line setting turns every page's duplicate into a redirect.

After changing the setting, check three things on a preview deployment: that internal links in the HTML already use the canonical form (so readers never hit the redirect), that <link rel="canonical"> matches it, and that the sitemap lists only canonical URLs. Hugo's canonifyURLs and relativeURLs settings, and Eleventy's url filter with a correctly set pathPrefix, produce consistent links if they are configured once at the site level rather than per template.

Headers and Caching

Vercel serves static files with Cache-Control: public, max-age=0, must-revalidate by default, relying on its CDN to cache them. For fingerprinted assets — Hugo Pipes with fingerprint, or an Eleventy asset pipeline that adds hashes — tell browsers to keep them for a year:

{
  "headers": [
    {
      "source": "/(.*)\\.([a-f0-9]{8,})\\.(css|js|woff2|avif|webp)",
      "headers": [{ "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }]
    },
    {
      "source": "/(.*)",
      "headers": [
        { "key": "Strict-Transport-Security", "value": "max-age=63072000; includeSubDomains" },
        { "key": "X-Content-Type-Options", "value": "nosniff" },
        { "key": "Referrer-Policy", "value": "strict-origin-when-cross-origin" },
        { "key": "Content-Security-Policy", "value": "default-src 'self'; img-src 'self' data:" }
      ]
    }
  ]
}

source patterns use path-to-regexp syntax, so test them carefully; a pattern that does not match silently applies nothing. Check headers on a preview deployment with curl -I before promoting. Background on the values is in Cache Busting with Content-Hashed Filenames and Writing a Content Security Policy for a Static Site.

Redirects and Rewrites

Redirects move from _redirects files, which Vercel ignores, into vercel.json:

{
  "redirects": [
    { "source": "/blog/:year/:month/:slug/", "destination": "/posts/:slug/", "permanent": true },
    { "source": "/old-docs/:path*", "destination": "/docs/:path*", "permanent": true }
  ],
  "rewrites": [
    { "source": "/api/:path*", "destination": "https://api.example.com/:path*" }
  ]
}

permanent: true sends a 308; false sends a 307. Vercel limits a project to 2,048 redirects in vercel.json. Beyond that, use a single rewrite to an edge function that looks paths up in a JSON map, or Vercel's bulk redirects where available. Hugo's aliases front matter generates meta-refresh HTML pages for moved content; on Vercel, prefer real redirects for better behaviour with search engines and set disableAliases = true once they are in place.

A small script can translate an existing _redirects file into vercel.json entries.

Previews and Environment-Specific Output

Every push to a non-production branch gets a preview URL. Use Vercel's system environment variables to change build output per environment: Hugo can read VERCEL_ENV and VERCEL_URL through os.Getenv in templates or be given --baseURL "https://$VERCEL_URL/" in the build command for previews, so absolute links and canonical tags point at the preview instead of production. Eleventy can read the same variables in a global data file. Add X-Robots-Tag: noindex for previews with a header rule conditioned on the host, or with Vercel's default preview protection. More on preview workflows in Preview Environments for Pull Requests.

Deploying From CI Instead of the Git Integration

The Git integration builds on Vercel's infrastructure, which is simple but means your build runs in an image you do not control. For stricter setups, build in your own CI and upload only the output: vercel pull --environment=production fetches project settings, vercel build --prod produces the Build Output API folder locally, and vercel deploy --prebuilt --prod uploads it. The same checks that run on pull requests — link checks, Lighthouse, HTML validation — then run against exactly the files that are deployed, and the Hugo or Node version is whatever your CI pins. Disable automatic Git deployments in the project settings so the two paths do not race each other.

Build Caching

Vercel caches node_modules between builds automatically for Eleventy. For Hugo, it caches the build image but not Hugo's own resources/_gen folder, so image processing reruns every build unless resources/ is committed to the repository — which many Hugo sites do for exactly this reason. For Eleventy image processing, point @11ty/eleventy-img's cache at .cache, which Vercel preserves between builds. See Caching Hugo Builds in GitHub Actions for the equivalent outside Vercel.

Measured Impact

A 900-page Hugo documentation site moved from Netlify to Vercel. The first build failed because the default Hugo version predated the theme's minimum; pinning HUGO_VERSION fixed it. A header and redirect conversion script translated 410 _redirects lines and 12 _headers rules into vercel.json. Setting trailingSlash: true removed 900 duplicate URL pairs that the first deploy had exposed. After cutover, TTFB and cache hit rates were within a few percent of the previous host, and preview URLs with noindex replaced the old deploy previews.

Pitfalls & Rollback

Unpinned Hugo. Always set HUGO_VERSION, and the extended edition if needed.
Leftover _headers and _redirects. They are ignored; convert them or the rules silently disappear.
trailingSlash mismatch with generator URLs. Produces redirect loops or duplicates; match your canonical form.
Headers pattern syntax. Test each source on a preview; an unmatched pattern applies nothing.
Rollback: Vercel keeps previous deployments; promote the last good one from the dashboard or with vercel promote.

Conclusion

Hugo and Eleventy run well on Vercel once the defaults are made explicit. Pin the generator and Node versions, set the build command and output directory in vercel.json, choose trailing slash and clean URL behaviour that matches your canonical URLs, and move headers and redirects from host-specific files into vercel.json. Use preview environment variables for correct base URLs, keep image caches between builds, and the site behaves the same on Vercel as it did locally.

FAQ

How do I set the Hugo version on Vercel?

Set the HUGO_VERSION environment variable in the project settings or in vercel.json build env, for example 0.134.0. Without it, Vercel's build image may use an old Hugo release that lacks features your theme needs, and builds can break or differ from local ones.

Parent: Netlify vs Vercel Deployment Strategies — choosing and configuring a platform.
Netlify Redirects and Rewrites for Static Sites — the rules you may be converting.
Vercel ISR vs Static Generation for SSGs — when static output is not enough.
Hugo Build Times for Large Repositories — keeping Hugo builds fast.
Enabling Incremental Builds in Eleventy — faster Eleventy builds.