Create a WEBSITE_URL env variable for all environments

Overview

When deploying a Next.js application on Vercel, you may need to access your website url in code to craft URLs and links to your apps for various needs.

Use cases:

Create a magic login link and send it via email
Crafting a webhook URL to be called by an external API
Configuring OAuth in all environments
Testing Open Graph in all environments
Create absolute URLs for various application needs
Add canonical URLs

The URL requirements are usually:

It must be available in server (Route Handler, Server Actions, …) and client code.
It must be valid and relevant for development, preview, and production environments
- in development: https://localhost:3000 or similar
- in Preview Deployments: the GIT branch url, so you can easily share a static URL of your upcoming feature. Example: https://some-project-git-new-feature-project.vercel.app . This URL will not change between commits/deployments to your branch.
- in production: https://vercel.com

If you want to do so when using Next.js and Vercel, here's how:

Solution

We’ll create a NEXT_PUBLIC_WEBSITE_URL environment variable that is usable in all environments and situations. We’re prefixing it with NEXT_PUBLIC so it’s available in the context of the server and client.

For development:

Create a .env.development.local file
Add NEXT_PUBLIC_WEBSITE_URL=http://localhost:3000 in it.
1. localhost:3000 could be a domain pointing to your local Next.js instance. In my setup, I love using ngrok with a custom domain, so I can test everything locally as if it was deployed on the internet.

For Preview Deployments:

Create a .env.production file (yes, Preview Deployments use NODE_ENV=production, so they use this file).
Add NEXT_PUBLIC_WEBSITE_URL=https://$NEXT_PUBLIC_VERCEL_BRANCH_URL
1. In most cases, this is what you want: a static branch url that won't change between commits to your branch. Alternatively, you can use NEXT_PUBLIC_WEBSITE_URL=https://$VERCEL_URL, which points to the Generated Deployment URL.

For production:

We’ll add a dedicated environment variable for production only:

Go to your project in the Vercel Dashboard
Click on the Settings tab (top right)
Click on Environment Variables
Create a new environment variable named (you guessed it) NEXT_PUBLIC_WEBSITE_URL
The value should be your production domain, like https://vercel.com

CleanShot 2024-08-28 at 18.00.07@2x

Ensure to check Automatically expose System Environment Variables in this UI too, which should be the default of any new Vercel project.

Alternatively, you can define a value of https://$VERCEL_PROJECT_PRODUCTION_URL in the UI, which will then expand to the shortest production domain for your project or a vercel.app domain if no production domain is configured.

Use the new environment variable:

Now, whenever you need to craft an absolute URL pointing to:

Your local server
The preview branch url
The production domain

You can do this in code:

1const url = `{$process.env.NEXT_PUBLIC_WEBSITE_URL}/never-gonna-give-you-up.mp4`;

That's it!

Resources

https://vercel.com/docs/projects/environment-variables/system-environment-variables

https://nextjs.org/docs/pages/building-your-application/configuring/environment-variables

https://vercel.com/docs/deployments/generated-urls