Vercel Deployments
Relevant source files
The following files were used as context for generating this wiki page:
Vercel Deployments provide an automated workflow for building and deploying applications from an Nx workspace to the Vercel platform. This system utilizes a dedicated Nx plugin, @nx-extend/vercel, to interface with the Vercel CLI and manage project configurations within a monorepo structure.
The deployment process handles pre-built artifacts, environment variable management, and team-based project association. It supports various deployment environments, including preview and production, and allows for regional configuration and debugging.
Sources: packages/vercel/README.md:1-15, packages/vercel/src/executors/deploy/deploy.impl.ts:16-35
Core Architecture and Execution
The deployment system relies on Nx executors to wrap Vercel CLI commands. The deploy executor specifically manages the final upload and activation of the application.
Execution Flow
The deployExecutor function initiates a command-line interface call to Vercel. It constructs a command using the --prebuilt flag, which assumes a build step has already occurred. If the Nx configuration name is production or the deployment option is set to production, the executor appends the --prod flag.
The diagram shows the logic within the deployment executor that prepares and executes the CLI command.
Sources: packages/vercel/src/executors/deploy/deploy.impl.ts:16-30, packages/vercel/executors.json:7-11
Configuration Options
Deployment behavior is controlled via project.json or command-line arguments passed to the executor.
Deploy Executor Schema
The following parameters are available for the deploy executor:
| Option | Type | Description |
|---|---|---|
regions | string | Specific Vercel regions to deploy the application to. |
buildTarget | string | The Nx target responsible for generating the build artifacts. |
archive | string | The archive type (e.g., tgz) used when uploading the build. |
deployment | string | Sets the environment to preview or production. |
debug | boolean | Enables Vercel debug mode for troubleshooting. |
Sources: packages/vercel/src/executors/deploy/schema.json:7-32, packages/vercel/README.md:43-50
Build Executor Integration
Before deployment, the build executor must generate the necessary Vercel artifacts. This requires project-specific identifiers from the Vercel dashboard.
| Option | Type | Description |
|---|---|---|
projectId | string | Vercel Project ID found in Project Settings. |
orgId | string | Vercel Organization (Team) ID. |
Sources: packages/vercel/README.md:25-33, packages/vercel/executors.json:2-6
Environment and Security
The system supports the VERCEL_TOKEN environment variable for authentication in CI/CD environments. When this variable is present, the executor automatically appends it to the deployment command.
GitHub Actions Integration
The system previously supported writing the Vercel deployment URL directly to the GitHub Job Summary. While currently commented out in the implementation, the logic identifies the deployment URL by parsing CLI output for strings starting with https:// and ending with .vercel.app.
Sources: packages/vercel/src/executors/deploy/deploy.impl.ts:28, packages/vercel/src/executors/deploy/deploy.impl.ts:37-60, packages/vercel/CHANGELOG.md (v1.6.0)
Implementation Details
The implementation uses @nx-extend/core utilities to handle process execution and command building.
// From packages/vercel/src/executors/deploy/deploy.impl.ts:25-33
const { success, output } = execCommand(buildCommand([
`${VERCEL_COMMAND} deploy --prebuilt`,
(context.configurationName === 'production' || options.deployment === 'production') && '--prod',
VERCEL_TOKEN && `--token=${VERCEL_TOKEN}`,
options.regions && `--regions=${options.regions}`,
options.archive && `--archive=${options.archive}`,
USE_VERBOSE_LOGGING && '--debug'
]), {
cwd: projectRoot
})
Sources: packages/vercel/src/executors/deploy/deploy.impl.ts:25-33
Summary
Vercel Deployments through the @nx-extend/vercel plugin streamline the delivery of applications by integrating Vercel's CLI directly into Nx workflows. By enforcing a --prebuilt deployment strategy, the system ensures that the exact artifacts generated by the Nx build process are what reach the Vercel edge network, providing consistency across different deployment environments.