Local Development Environments

Understand how to work with local development environments and how to configure environment variables for local development.
Table of Contents

Sometimes called "local" or "development", this environment is where you work on your codebase, make changes, and test them on your local computer before deploying them to the Vercel. This environment is not connected to the Vercel platform and is used to test your application before deploying it to Vercel.

  1. Install Vercel CLI to interact with Vercel from your command line:
    Terminal
    npm install -g vercel
  2. Use vercel dev to run your project locally with Vercel's development server. Your framework may also have specific local development commands.
  3. Use .env.local file to specify local environment variables. This environment mimics the Vercel platform locally, allowing you to catch issues early on.

You need Vercel CLI version 21.0.1 or higher to use the features described in this section.

Environment variables for local development are defined in the .env.local file. This is a plain text file that contains key=value pairs of environment variables, that you can manually create in your project's root directory to define specific variables.

You can use the vercel env pull command to automatically create and populate the .env file (which serves the same purpose as .env.local) with the environment variables from your Vercel project:

vercel env pull
Downloading Development Environment Variables for Project my-lovely-project
✅ Created .env file [510ms]

This command creates a .env file in your project's current directory with the environment variables from your Vercel project's Development environment.

If you're using vercel dev, there's no need to run vercel env pull, as vercel dev automatically downloads the Development Environment Variables into memory. For more information on the vercel env command, see the CLI docs.

To work with the .env.local file:

  1. Create the file in your project's root directory if it doesn't exist or run vercel env pull as described above.
  2. Add your environment variables in the format KEY=VALUE, one per line:
    .env.local
    API_KEY=your_api_key_here
    DATABASE_URL=your_database_url_here
  3. Ensure the environment variables are loaded into your dev server. Most JavaScript frameworks do this automatically, but you may wish to refer to your framework's documentation. To access the variables in your application code, you can use process.env.KEY. For example:
    const apiKey = process.env.API_KEY;
    const databaseUrl = process.env.DATABASE_URL;

Your env.local file should not be committed to your repository as it's meant for local development only and often contains sensitive information like API keys and secrets. For this reason, you should ensure that the .env.local file is added to your .gitignore file:

.gitignore
.env.local
*.local

For team collaboration on local development environments, you should use the Vercel dashboard to manage environment variables. This allows you to share environment variables with your team and keep them in sync across all local development environments.

Environment variables defined in .env.local take precedence over those defined in .env. This allows you to override variables for your local development environment without affecting other environments or team members.

Last updated on September 11, 2024