Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
tf-next build
✓ tf-next build <path/to/next-app>
Primary command to compile and optimize your Next.js application for AWS Lambda and S3 deployment. Run from the directory containing `next.config.js` or `package.json`.
tf-next deploy
✓ tf-next deploy <path/to/next-app> --profile my-aws-profile --endpoint https://<api-id>.execute-api.<region>.amazonaws.com
New in v1.0.0-canary.2, this command deploys the previously built application to the specified AWS environment. It requires an active AWS CLI profile and the API endpoint provided by your Terraform module output.
tf-next
✓ tf-next --version
✗ import { tfNext } from 'tf-next'
tf-next is a global CLI executable, not a library for programmatic import within JavaScript/TypeScript code. All interactions are via shell commands.
Demonstrates the global installation of the `tf-next` CLI, followed by the essential steps to build a Next.js application and deploy it to AWS. This covers the typical workflow for local development or within a CI/CD pipeline, including specifying an AWS profile and the API endpoint from your Terraform setup.
npm install -g tf-next@canary
# Navigate to your Next.js application root (e.g., where package.json is)
cd my-next-app
# Step 1: Build the Next.js application for deployment
# This creates a '.next-tf' folder with deployment artifacts.
tf-next build .
# Step 2: Deploy the built application to AWS
# This command interacts with the Terraform-provisioned AWS API Gateway endpoint.
# Replace `my-aws-profile` with your configured AWS CLI profile.
# Replace `https://<api-id>.execute-api.<region>.amazonaws.com` with the `api_endpoint` output from your Terraform module.
tf-next deploy . --profile my-aws-profile --endpoint https://<api-id>.execute-api.<region>.amazonaws.com
# For v1.0.0-canary.2 and newer, `tf-next deploy` without arguments might be used
# after initial configuration, for managing atomic deployments and aliases.
# For example, to set an alias for a deployment:
# tf-next alias production-domain
tf-next --version
Debug
Known issues
breakingThe `terraform-aws-next-js` module and `tf-next` CLI now explicitly require AWS Provider Version `v4.15.0` or higher. Upgrading from v3 or older v4 providers requires following the official Terraform AWS Provider v4 Upgrade Guide.fixUpdate your Terraform AWS provider to `v4.15.0` or newer in your Terraform configuration (e.g., `required_providers { aws = { source = "hashicorp/aws", version = "~> 4.15" } }`) and run `terraform init -upgrade`. affects: >=0.13.0
breakingWhen attaching additional policies to the Lambda role, the `lambda_policy_json` variable must now be used. This change impacts how fine-grained permissions are applied to your Next.js Lambda functions.fixAdjust your Terraform configuration to utilize the `lambda_policy_json` variable for policy attachments as per the module's documentation.
affects: >=0.12.0
gotchaRedirects issued by the proxy module now use `Cache-Control: public, max-age=0, must-revalidate` instead of `Cache-Control: public, max-age=31536000, immutable`. This prevents CloudFront from caching redirects, ensuring dynamic redirect updates are reflected immediately.fixNo direct fix needed, but be aware of the altered caching behavior for redirects. If previous setups relied on long-term caching for redirects, this behavior will change.
affects: >=0.12.2
gotchaFor v1.0.0-canary releases, new CLI actions (`deploy`, `alias`, `deployment`) have been introduced alongside a new atomic deployment model. Existing commands or workflows might need to be adapted to leverage these new features.fixConsult the latest `tf-next` documentation or `tf-next --help` for the correct usage of the new deployment commands, especially when migrating to or using the canary versions. Ensure your Terraform module configuration (`enable_multiple_deployments = true`) supports these new features.
affects: >=1.0.0-canary.2
Errors
Common errors & fixes
Error: @vercel/nft was not available
A regression in the `tf-next build` command where the internal `@vercel/nft` dependency, crucial for Next.js build optimization, was not correctly packaged or accessible.
fixUpgrade `tf-next` to version `0.13.2` or higher. This issue was resolved in the `v0.13.2` bugfix release.
CLI installation issues or `tf-next` command not found after installation.
Bugs related to the installation process itself, which could lead to an incomplete installation or incorrect pathing for the global executable.
fixUpgrade `tf-next` to `v1.0.0-canary.4` or higher. This release specifically addressed installation-related bugs. Ensure npm/yarn global binaries are correctly added to your system's PATH.
The `--profile` (or `--awsProfile`) flag is not being recognized or applied correctly during CLI execution, leading to AWS authentication failures or use of the wrong profile.
A bug in the CLI's parsing or handling of the AWS profile flag, preventing it from correctly using specified AWS credentials.
fixUpgrade `tf-next` to `v1.0.0-canary.5` or higher. This version includes a fix for the `--profile` and `--awsProfile` flags, improving their reliability.
Audit
Dependencies
No dependency data recorded yet.