{"id":14127,"library":"tf-next","title":"tf-next CLI for AWS Next.js Deployments","description":"tf-next is a specialized Command Line Interface (CLI) build tool designed to streamline the deployment of Next.js applications to Amazon Web Services (AWS) using Terraform. It acts as a companion to the `milliHQ/terraform-aws-next-js` Terraform module, automating the build process, managing deployments, and configuring associated AWS resources. The current stable version is `0.13.2`, though `1.0.0-canary` releases are actively introducing significant features such as atomic deployments and preview environments, indicating a rapid development pace. Key differentiators include its tight integration with Terraform for infrastructure-as-code deployments, support for Next.js image optimization, and the ability to serve multiple Next.js applications from a single CloudFront distribution with preview deployment capabilities, greatly enhancing multi-environment and A/B testing scenarios.","status":"active","version":"0.13.2","language":"javascript","source_language":"en","source_url":"https://github.com/milliHQ/terraform-aws-next-js","tags":["javascript"],"install":[{"cmd":"npm install tf-next","lang":"bash","label":"npm"},{"cmd":"yarn add tf-next","lang":"bash","label":"yarn"},{"cmd":"pnpm add tf-next","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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`.","symbol":"tf-next build","correct":"tf-next build <path/to/next-app>"},{"note":"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.","symbol":"tf-next deploy","correct":"tf-next deploy <path/to/next-app> --profile my-aws-profile --endpoint https://<api-id>.execute-api.<region>.amazonaws.com"},{"note":"tf-next is a global CLI executable, not a library for programmatic import within JavaScript/TypeScript code. All interactions are via shell commands.","wrong":"import { tfNext } from 'tf-next'","symbol":"tf-next","correct":"tf-next --version"}],"quickstart":{"code":"npm install -g tf-next@canary\n\n# Navigate to your Next.js application root (e.g., where package.json is)\ncd my-next-app\n\n# Step 1: Build the Next.js application for deployment\n# This creates a '.next-tf' folder with deployment artifacts.\ntf-next build .\n\n# Step 2: Deploy the built application to AWS\n# This command interacts with the Terraform-provisioned AWS API Gateway endpoint.\n# Replace `my-aws-profile` with your configured AWS CLI profile.\n# Replace `https://<api-id>.execute-api.<region>.amazonaws.com` with the `api_endpoint` output from your Terraform module.\ntf-next deploy . --profile my-aws-profile --endpoint https://<api-id>.execute-api.<region>.amazonaws.com\n\n# For v1.0.0-canary.2 and newer, `tf-next deploy` without arguments might be used \n# after initial configuration, for managing atomic deployments and aliases.\n# For example, to set an alias for a deployment:\n# tf-next alias production-domain\n","lang":"javascript","description":"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."},"warnings":[{"fix":"Update 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`.","message":"The `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.","severity":"breaking","affected_versions":">=0.13.0"},{"fix":"Adjust your Terraform configuration to utilize the `lambda_policy_json` variable for policy attachments as per the module's documentation.","message":"When 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.","severity":"breaking","affected_versions":">=0.12.0"},{"fix":"No 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.","message":"Redirects 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.","severity":"gotcha","affected_versions":">=0.12.2"},{"fix":"Consult 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.","message":"For 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.","severity":"gotcha","affected_versions":">=1.0.0-canary.2"}],"env_vars":null,"search_vec":"'0.13.2':62 '1.0.0':64 'a/b':126 'abil':105 'act':37 'activ':68 'amazon':30 'applic':28,110 'associ':54 'atom':74 'autom':46 'aw':6,33,55 'build':19,48 'canari':65 'capabl':119 'cli':4,18 'cloudfront':114 'code':96 'command':15 'companion':40 'configur':53 'current':58 'deploy':8,25,51,75,97,118 'design':21 'develop':82 'differenti':85 'distribut':115 'enhanc':121 'environ':78,124 'featur':71 'great':120 'imag':101 'includ':86 'indic':79 'infrastructur':94 'infrastructure-as-cod':93 'integr':89 'interfac':17 'introduc':69 'javascript':129 'key':84 'line':16 'manag':50 'millihq/terraform-aws-next-js':43 'modul':45 'multi':123 'multi-environ':122 'multipl':108 'next':3,11 'next.js':7,27,100,109 'optim':102 'pace':83 'preview':77,117 'process':49 'rapid':81 'releas':66 'resourc':56 'scenario':128 'serv':107 'servic':32 'signific':70 'singl':113 'special':14 'stabl':59 'streamlin':23 'support':98 'terraform':35,44,91 'test':127 'tf':2,10 'tf-next':1,9 'though':63 'tight':88 'tool':20 'use':34 'version':60 'web':31","created_at":"2026-04-20T01:58:03.887053+00:00","updated_at":"2026-04-20T01:58:03.887053+00:00","problems":[{"fix":"Upgrade `tf-next` to version `0.13.2` or higher. This issue was resolved in the `v0.13.2` bugfix release.","cause":"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.","error":"Error: @vercel/nft was not available"},{"fix":"Upgrade `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.","cause":"Bugs related to the installation process itself, which could lead to an incomplete installation or incorrect pathing for the global executable.","error":"CLI installation issues or `tf-next` command not found after installation."},{"fix":"Upgrade `tf-next` to `v1.0.0-canary.5` or higher. This version includes a fix for the `--profile` and `--awsProfile` flags, improving their reliability.","cause":"A bug in the CLI's parsing or handling of the AWS profile flag, preventing it from correctly using specified AWS credentials.","error":"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."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"tf-next","cli_version":null,"type":"library","homepage":"https://registry.terraform.io/modules/milliHQ/next-js/aws","github":"https://github.com/milliHQ/terraform-aws-next-js","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/tf-next","openapi_spec":null,"status_page":null,"smithery":null,"categories":["aws","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}