Local Development Environments
Understand how to work with local development environments and how to configure environment variables for local development.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.
- Install Vercel CLI to interact with Vercel from your command line:
Terminal
npm install -g vercel
- Use
vercel dev
to run your project locally with Vercel's development server. Your framework may also have specific local development commands. - 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:
- Create the file in your project's root directory if it doesn't exist or run
vercel env pull
as described above. - Add your environment variables in the format
KEY=VALUE
, one per line:.env.localAPI_KEY=your_api_key_here DATABASE_URL=your_database_url_here
- 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:
.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.
Was this helpful?