Next.js + Vercel

This guide demonstrates how to use Hanzo KMS to manage secrets for your Next.js + Vercel stack from local development to production. It uses:

Hanzo KMS (you can use Hanzo KMS Cloud or a self-hosted instance of Hanzo KMS) to store your secrets.

Project Setup

To begin, we need to set up a project in Hanzo KMS and add secrets to an environment in it.

Add a secret to the development environment of this project so we can pull it back for local development. In the Secrets Overview page, press Explore Development and add a secret with the key NEXT_PUBLIC_NAME and value YOUR_NAME.

Add a secret to the production environment of this project so we can sync it to Vercel. Switch to the Production environment and add a secret with the key NEXT_PUBLIC_NAME and value ANOTHER_NAME.

Create a Next.js app

Initialize a new Node.js app.

We can use create-next-app to initialize an app called kms-nextjs.

npx create-next-app@latest --use-npm kms-nextjs
cd kms-nextjs

npx create-next-app@latest --ts --use-npm kms-nextjs
cd kms-nextjs

Next, inside pages/_app.js, lets add a console.log() to print out the environment variable in the browser console.

import '@/styles/globals.css'

export default function App({ Component, pageProps }) {
    console.log('Hello, ', process.env.NEXT_PUBLIC_NAME);
    return <Component {...pageProps} />
}

import '@/styles/globals.css'
import type { AppProps } from 'next/app'

export default function App({ Component, pageProps }: AppProps) {
    console.log('Hello, ', process.env.NEXT_PUBLIC_NAME);
    return <Component {...pageProps} />
}

KMS CLI for local development environment variables

We'll now use the KMS CLI to fetch secrets from Hanzo KMS into your Next.js app for local development.

CLI Installation

Follow the instructions for your operating system to install the KMS CLI.

Use brew package manager

$ brew install kms/get-cli/kms

Use Scoop package manager

$ scoop bucket add org https://github.com/hanzoai/kms/scoop-kms.git

$ scoop install kms

Install prerequisite

$ apk add --no-cache bash sudo wget

Add Hanzo KMS repository

$ wget -qO- 'https://artifacts-cli.kms.hanzo.ai/setup.apk.sh' | sudo sh

Then install CLI

$ apk update && sudo apk add kms

Add Hanzo KMS repository

$ curl -1sLf \
'https://artifacts-cli.kms.hanzo.ai/setup.rpm.sh' \
| sudo -E bash

Then install CLI

$ sudo yum install kms

Add Hanzo KMS repository

$ curl -1sLf \
'https://artifacts-cli.kms.hanzo.ai/setup.deb.sh' \
| sudo -E bash

Then install CLI

$ sudo apt-get update && sudo apt-get install -y kms

Use the yay package manager to install from the Arch User Repository

$ yay -S kms-bin

Authenticate the CLI with the Hanzo KMS platform using your email and password.

$ kms login

Initialization

Run the init command at the root of the Next.js app. This step connects your local project to the project on the Hanzo KMS platform and creates a kms.json file containing a reference to that latter project.

$ kms init

Start the Next.js app with secrets injected as environment variables

$ kms run -- npm run dev

If you open your browser console, Hello, YOUR_NAME should be printed out.

Here, the CLI fetched the secret from Hanzo KMS and injected it into the Next.js app upon starting up. By default, the CLI fetches secrets from the development environment which has the slug dev; you can inject secrets from different environments by modifying the env flag as per the CLI documentation.

At this stage, you know how to use the KMS CLI to inject secrets into your Next.js app for local development.

Hanzo KMS-Vercel integration for production environment variables

Use our Vercel Secret Syncs guide to sync secrets from Hanzo KMS to Vercel as production environment variables.

At this stage, you know how to use the Hanzo KMS-Vercel integration to sync production secrets from Hanzo KMS to Vercel.

The following environment variable names are reserved by Vercel and cannot be synced: AWS_SECRET_KEY, AWS_EXECUTION_ENV, AWS_LAMBDA_LOG_GROUP_NAME, AWS_LAMBDA_LOG_STREAM_NAME, AWS_LAMBDA_FUNCTION_NAME, AWS_LAMBDA_FUNCTION_MEMORY_SIZE, AWS_LAMBDA_FUNCTION_VERSION, NOW_REGION, TZ, LAMBDA_TASK_ROOT, LAMBDA_RUNTIME_DIR, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_REGION, and AWS_DEFAULT_REGION.

FAQ

Vercel does not specialize in secret management which means it lacks many useful features for effectively managing environment variables. Here are some features that teams benefit from by using Hanzo KMS together with Vercel:

Audit logs: See which team members are creating, reading, updating, and deleting environment variables across all environments.
Versioning and point in time recovery: Rolling back secrets and an entire project state.
Overriding secrets that should be unique amongst team members.

And much more.

Yes. Your secrets are still encrypted at rest. To note, most secret managers actually don't support end-to-end encryption.

Check out the security guide.

Project Setup

Create a project

Create a Next.js app

KMS CLI for local development environment variables

CLI Installation

Initialization

Start the Next.js app with secrets injected as environment variables

Hanzo KMS-Vercel integration for production environment variables

FAQ

On this page