VERCEL_URL not available at build time if built outside of Vercel

[dbianchii (Gabriel Bianchi)]

Hi Vercel team,

We’re currently deploying a Next.js app with preview environments on Vercel and ran into an issue with the VERCEL_URL environment variable.
Our build step runs on GitHub Actions, (remotely deployed with vercel deploy --prebuilt). not on Vercel directly.

Our goal is to compute the application’s BASE_URL at build time, but we noticed that:
• VERCEL_URL is not available during the build step at all for deployments happening outside of Vercel. (contrary to what is said here – likely the docs should be updated)
• It only becomes available at runtime (e.g., inside API routes or serverless functions).
• This breaks our logic that needs the base preview URL to be known during static generation (e.g., for SEO, OG tags, etc).

We’re aware that:
• The preview URL is generated on Vercel’s side after the build finishes.
• Therefore, it can’t be injected during the build step by default.

However, this makes it impossible to reference the actual URL in places like:

export const metadata: Metadata = {
  previewImageUrl: `${getBaseUrl()}/preview-image.png`
};

We are utilizing a function like this to get the baseUrl:

const getBaseUrl = () => {
  if (typeof window !== 'undefined') {
    return window.location.origin;
  }

  if (process.env.VERCEL) {
    // env.VERCEL is truthy for builds with 'vercel build' even outside of vercel (like GH actions)

    if (process.env.NEXT_PUBLIC_ALIAS_URL) {
      // production/staging urls we have custom set.
      return `https://${process.env.NEXT_PUBLIC_ALIAS_URL}`; // (also available at build time)
    }
    if (process.env.VERCEL_URL) {
      return `https://${process.env.VERCEL_URL}`; // (not available at build time if built outside of vercel like GH actions)
    }
    // TODO: Find a way to get the base url for preview builds
  }
  return `http://localhost:${process.env.PORT ?? 3000}`;
};

How can we access the base url of preview environments at build time if the build is not happening at Vercel?

[system]

The domain troubleshooting guide can help with most custom domain configuration issues. You might be able to use that guide to solve it before a human is available to help you. Then you can come back here and share the answer for bonus points.

Troubleshooting domains

You can also use v0 to narrow down the possibilities.

[jakeleventhal]

[jacobparis]

There is no way to get the VERCEL_URL outside of Vercel. One build could be deployed to multiple preview environments and each could have a different URL.

Instead you would have to generate your own URL to use at build time in your GitHub Action, and instruct Vercel to alias your preview deployment to the URL you chose.

If you’re not using the Git Integration, vercel alias is a great solution if you still need to apply custom domains based on Git branches, or other heuristics.

vercel alias

  Examples:

  - Add a new alias to `my-api.vercel.app`
    $ vercel alias set api-ownv3nc9f8.vercel.app my-api.vercel.app

  - Custom domains work as alias targets
    $ vercel alias set api-ownv3nc9f8.vercel.app my-api.com

  - The subcommand `set` is the default and can be skipped. Protocols in the URLs are unneeded and ignored
    $ vercel alias api-ownv3nc9f8.vercel.app my-api.com

[jakeleventhal]

Hey @jacobparis that is exactly the issue. The proposal for this feature is to allow building locally without needing to use a Vercel worker.

There is no way to get the VERCEL_URL outside of Vercel

The proposal is to add some CLI flag or something to either set a predefined unique alias at build time or to have some step that reserves an alias at build time. The point here is that if you want a build-time environment variable for the domain alias it is not possible unless you build inside Vercel.

I think the predefined alias would be sufficient. For example

vercel build –alias=myapp-somehash.vercel.app

Or perhaps if there were some deterministic way to know the alias, for example using the commit hash that could work too.

[jacobparis]

Builds do not have aliases, they are essentially just static files. If you mean you just want the VERCEL_URL variable to have the correct value at build time, you can set it in this way for the build, and then re-use that for the alias

VERCEL_URL=myapp-somehash.vercel.app vercel build
DEPLOY_URL=$(vercel deploy --prebuilt --prod)
vercel alias "$DEPLOY_URL" "$VERCEL_URL" 

> Success! https://myapp-somehash.vercel.app now points to https://asdfasdfasdf-asdfasdf-jacob-paris-projects.vercel.app [1s]

[jakeleventhal]

Mashallah this works. Thanks