Aliasing a Deployment

When deploying a project, whether ready for staging or production, you will want a URL to share the project with others or for yourself to check on other devices.

Aliases are Now's method for creating a link to the latest, or chosen deployment with a custom URL with zero-downtime for each alias transition.

There are two ways to create an alias with Now:

Deployment Environments

When making a deployment, you can choose whether to push that deployment to production or to a staging URL.

Staging

Every new deployment, whether it is from Now CLI, Now for GitHub, or Now for GitLab, will receive both a unique deployment URL and a staging alias for the deployment that updates with every deployment you personally make from the project.

The staging alias can be formatted in multiple ways, depending on where it came from.

These staging aliases include:

Personal Project Staging Aliases

For deployments made from a personal account with Now CLI, you will get a staging alias like the following:

Breakdown of a personal staging alias.

In the above example, each deployment from the personal account with the username timothy to their my-app project will result in an update with the latest app to the staging alias URL my-app.timothy.now.sh.

This alias is helpful when you want to share a non-production URL containing the latest changes of a personal project with automatic updates for each deployment.

Default Staging Aliases for a Team's Project

Deployments made in a team's scope with Now CLI, by default, will result in a staging alias like the following:

Breakdown of a default staging alias for a project in a team.

In the above example, each deployment from the team scope my-team by a team member with the username timothy to the my-app project will result in an update with the latest app to the staging alias URL my-app-timothy.my-team.now.sh.

This default alias is helpful when you want to share the URL containing the latest changes of a single team member for a project that automatically updates with each new deployment.

Staging Environment Aliases for a Team's Project

Deployments made in a team's scope with Now CLI using the --target staging option, will result in a staging alias like the following:

Breakdown of an alias for the staging deployment environment for a team's project.

In the above example, each deployment with the following command, from the team scope my-team by a team member with the username timothy to the my-app project will result in an update with the latest app to the staging alias URL my-app.my-team.now.sh:

now --target staging

This environment alias is helpful when you are working on a project as a team and want to share a URL of the combined efforts of multiple team members, updated with each deployment with the staging target argument.

Git Staging Aliases

If you are using Now for GitHub or Now for GitLab, every push to a non-default branch will result in a staging alias with the following format:

Breakdown of an alias for the staging deployment environment for a team's project on a non-default Git branch.

In the above example, each push to the staging branch with the team scope my-team to the my-app project will result in an update with the latest app to the staging alias URL my-app-git-staging.my-team.now.sh.

If the non-default branch belongs to a repository connected to a personal Now user, the my-team portion of the alias will be replaced with the username of that account. For example; when the repository's owner is connected with the account timothy, the URL would be my-app-git-staging.timothy.now.sh.

Production

The production alias is a custom defined production environment, configured using the alias property of a now.json file.

{
  "version": 2,
  "alias": "my-zeit-domain.live"
}

An example now.json file configuring the Now platform version and a production alias.

Triggering a deployment to a production alias can be done with either Now CLI or automatically with a Now for Git integration.

Note: This production alias can be your added domain or a custom alias using the .now.sh suffix or a Custom Deployment Suffix.

With Now CLI

Deploying with the following command will trigger a deployment to the production alias defined in the now.json file:

now --target production

With Now for Git

Each push to the default branch with either Now for GitHub or Now for GitLab, will result in aliasing a fresh deployment to the production alias, set in your now.json file.

Manual Aliasing

Aside from automatic aliases through deployment environments, you can also manually alias your deployments using Now CLI.

Invoking the command now alias will create an alias between a provided deployment URL and a defined alias, using the following syntax:

now alias <SOURCE URL | ID> <TARGET SUBDOMAIN | DOMAIN>

You can manually alias to either your added domain or a subdomain of the .now.sh default suffix or Custom Deployment Suffix.

Aliasing to A Domain

The same mechanism used above can be used to configure a custom domain.

The command to alias a deployment to a domain is similar:

now alias https://get-started-hwbbrak5g.now.sh my-zeit-domain.com

If my-zeit-domain.com is not yet yours and is available to purchase, Now will allow you to buy it directly from the command-line, which is the only step you need to take. Now will take care of all the domain configuration.

Otherwise, you need to add the domain to your Now account or team.

Refer to the domains documentation for more information on domain configuration.

Aliasing to a URL with a Deployment Suffix

For example, say you want the deployment https://get-started-hwbbrak5g.now.sh to be accessible by the alias get-started.now.sh; running the following command will create this alias:

now alias https://get-started-hwbbrak5g.now.sh get-started

After this success message, your deployment is instantly available through the original input URL and the new alias you chose for it:

The URL get-started.now.sh now works!

Notice that the example command omitted .now.sh at the end of the target subdomain. When one is not given, Now defaults the alias value to use .now.sh as a suffix.

Note: You can use a Custom Deployment Suffix in place of .now.sh.

For convenience, we parse the URLs you supply as parameters to now alias to extract the hostname, which means the following are all valid source URLs:

  • Just the hostname: get-started-hwbbrak5g.now.sh
  • Including http(s): https://get-started-hwbbrak5g.now.sh
  • Including /: https://get-started-hwbbrak5g.now.sh/

Read More

The following resources are related to this topic and helpful with any path you would like to take next: