Vercel ZSH Script Explained: A Detailed Guide

by Alex Johnson 46 views

This comprehensive guide aims to break down a Vercel ZSH script, offering a detailed explanation of its functionalities and how it manages Vercel projects and domains. Whether you're a beginner or an experienced developer, understanding this script can significantly improve your deployment workflow on Vercel. This article provides a detailed walkthrough of the script, explaining each command and its purpose. By the end of this guide, you should have a solid understanding of how this script automates the management of Vercel projects and domains.

Script Overview

The script is written in Zsh (zsh), a Unix shell that is used as a command-line interpreter. This script automates the process of managing Vercel projects and domains. It performs several key tasks, including removing existing projects (excluding the main one), adding a new project, adding and removing domains, and setting up aliases. The primary goal is to streamline the deployment process by ensuring the correct project and domain configurations on Vercel.

Key Components

The script includes the following main components:

  1. Project Management: Deletes existing Vercel projects (excluding the main project) to maintain a clean environment.
  2. Domain Management: Adds and removes domains to ensure proper domain configuration for the project.
  3. Deployment: Deploys the project to Vercel with the correct settings and aliases.

Let's dive deeper into each section of the script to understand how it works.

Detailed Script Breakdown

The script starts with essential setup commands and then proceeds to manage Vercel projects, domains, and deployments. Below is a step-by-step explanation of each section.

1. Initial Setup

The script begins with the following lines:

#!/bin/zsh
set -e
  • #!/bin/zsh: This is a shebang, which specifies the interpreter for the script. In this case, it's Zsh.
  • set -e: This command ensures that the script will exit immediately if any command fails. This is crucial for automation scripts, as it prevents subsequent commands from running if a previous one has failed, ensuring that errors are caught early and the script doesn't proceed with a broken configuration.

2. Defining Variables

Next, the script defines several variables that are used throughout the script:

VERCEL_PROJECT_NAME="tryonyou-master"
VERCEL_DOMAIN_A="tryonyou.app"
VERCEL_DOMAIN_W="www.tryonyou.app"
  • VERCEL_PROJECT_NAME: This variable stores the name of the Vercel project, which is tryonyou-master.
  • VERCEL_DOMAIN_A: This variable stores the primary domain name, tryonyou.app.
  • VERCEL_DOMAIN_W: This variable stores the subdomain www.tryonyou.app. Using variables for these values makes the script more maintainable and easier to configure, as you can simply change the variable values at the beginning of the script rather than having to hunt through the code to find the specific instances where these values are used.

3. Removing Existing Projects

This section of the script removes all Vercel projects except the one specified in the VERCEL_PROJECT_NAME variable. This is useful for cleaning up old projects and ensuring that the environment is clean before deploying the new project.

vercel projects ls | grep -v "$VERCEL_PROJECT_NAME" | awk '{print $1}' | while read project; do
 vercel project rm "$project" --yes
done

Let's break down this command step by step:

  • vercel projects ls: Lists all Vercel projects.
  • grep -v "$VERCEL_PROJECT_NAME": Filters out the main project specified by VERCEL_PROJECT_NAME. The -v option in grep inverts the match, so it only includes lines that do not contain the project name.
  • awk '{print $1}': Extracts the first word from each line, which is the project ID.
  • while read project; do ... done: Loops through each project ID.
  • vercel project rm "$project" --yes: Removes the project. The --yes flag automatically confirms the deletion, preventing the script from prompting for confirmation and allowing it to run unattended.

This section ensures that your Vercel account doesn't become cluttered with old projects, which can simplify management and reduce the risk of deploying to the wrong project.

4. Adding the Main Project

This command adds the main project specified by VERCEL_PROJECT_NAME. If the project already exists, this command will not fail due to the || true at the end, which ignores the error.

vercel project add "$VERCEL_PROJECT_NAME" --yes || true
  • vercel project add "$VERCEL_PROJECT_NAME": Adds the project to Vercel. This command ensures that the project is set up correctly on Vercel's platform, which is a prerequisite for deploying to it.
  • --yes: Automatically confirms the project creation, which is useful in automated scripts to avoid manual intervention.
  • || true: This is a common shell scripting technique to ignore the exit status of a command. If the vercel project add command fails (e.g., because the project already exists), the || true will ensure that the script continues to run without exiting. This is a form of error handling that allows the script to proceed even if a non-critical command fails.

5. Adding Domains

This section adds the specified domains to the Vercel project. It ensures that the domains are correctly associated with the Vercel project, allowing traffic to be routed to your application.

vercel domains add "$VERCEL_DOMAIN_A" --yes || true
vercel domains add "$VERCEL_DOMAIN_W" --yes || true
  • vercel domains add "$VERCEL_DOMAIN_A": Adds the primary domain to Vercel.
  • vercel domains add "$VERCEL_DOMAIN_W": Adds the www subdomain to Vercel.
  • --yes: Automatically confirms the domain addition.
  • || true: Ignores errors, similar to the project addition command. This ensures that if a domain is already added, the script continues without interruption.

6. Removing and Re-adding Domains

This section ensures that the domains are correctly configured by first removing them and then re-adding them. This can be useful for resolving issues with domain configurations or ensuring that the latest settings are applied.

vercel domains ls | grep "$VERCEL_DOMAIN_A" | awk '{print $1}' | while read domain; do
 vercel domains rm "$domain" --yes || true
 vercel domains add "$VERCEL_DOMAIN_A" --yes || true
done

vercel domains ls | grep "$VERCEL_DOMAIN_W" | awk '{print $1}' | while read domain; do
 vercel domains rm "$domain" --yes || true
 vercel domains add "$VERCEL_DOMAIN_W" --yes || true
done

This section is broken down into two similar blocks, one for each domain ($VERCEL_DOMAIN_A and $VERCEL_DOMAIN_W). Let's analyze the first block:

  • vercel domains ls: Lists all domains associated with the Vercel account.
  • grep "$VERCEL_DOMAIN_A": Filters the list to only include the primary domain.
  • awk '{print $1}': Extracts the domain name.
  • while read domain; do ... done: Loops through each matching domain.
  • vercel domains rm "$domain" --yes || true: Removes the domain. The --yes flag bypasses the confirmation prompt, and || true ignores any errors (e.g., if the domain doesn't exist).
  • vercel domains add "$VERCEL_DOMAIN_A" --yes || true: Re-adds the domain. This step ensures that the domain is correctly set up on Vercel.

The second block does the same for the www subdomain ($VERCEL_DOMAIN_W).

7. Deploying to Production

This command deploys the project to Vercel's production environment. The --prod flag ensures that the deployment is treated as a production deployment, which can affect caching and other settings. The --yes flag bypasses any confirmation prompts.

vercel --prod --yes
  • vercel --prod: Deploys the project to the production environment.
  • --yes: Automatically confirms the deployment.

8. Setting Aliases

This section sets aliases for the domains, mapping them to the deployed project. This ensures that traffic to the domains is correctly routed to the Vercel deployment.

vercel alias set "$VERCEL_DOMAIN_A" "$VERCEL_PROJECT_NAME" --yes
vercel alias set "$VERCEL_DOMAIN_W" "$VERCEL_PROJECT_NAME" --yes
  • vercel alias set "$VERCEL_DOMAIN_A" "$VERCEL_PROJECT_NAME": Sets an alias for the primary domain, pointing it to the specified project.
  • vercel alias set "$VERCEL_DOMAIN_W" "$VERCEL_PROJECT_NAME": Sets an alias for the www subdomain, pointing it to the same project.
  • --yes: Automatically confirms the alias setting.

By setting up aliases, you ensure that your domains correctly point to your Vercel project, making your application accessible via these domains.

9. Final Output

The script concludes with a simple output to indicate that it has completed successfully.

echo "READY"
  • echo "READY": Prints "READY" to the console, signaling the successful completion of the script. This is a simple way to confirm that the script has run through all its steps without error.

Conclusion

This Zsh script is a powerful tool for automating Vercel project and domain management. By understanding each component of the script, you can customize it to fit your specific needs and streamline your deployment process. From cleaning up old projects to ensuring correct domain configurations and deploying to production, this script covers many essential tasks.

By automating these processes, you can reduce the risk of human error, save time, and ensure consistency across your deployments. If you are working with Vercel, understanding and utilizing scripts like this can significantly enhance your workflow and productivity.

For further reading on Vercel and its functionalities, you can visit the official Vercel documentation: Vercel Official Documentation.