serverless-dotenv-plugin

What is serverless-dotenv-plugin?

The serverless-dotenv-plugin is a Serverless Framework plugin that automatically loads environment variables from a .env file into your serverless project. This allows you to manage environment-specific configurations and secrets in a centralized and secure manner.

What are serverless-dotenv-plugin's main functionalities?

Load Environment Variables

This feature allows you to load environment variables from a .env file into your serverless project. The code sample demonstrates how to configure the serverless-dotenv-plugin in the serverless.yml file and access an environment variable in a function.

module.exports = {
  service: 'my-service',
  plugins: ['serverless-dotenv-plugin'],
  provider: {
    name: 'aws',
    runtime: 'nodejs14.x'
  },
  functions: {
    hello: {
      handler: 'handler.hello',
      environment: {
        MY_ENV_VAR: process.env.MY_ENV_VAR
      }
    }
  }
};

Custom .env File Path

This feature allows you to specify a custom path for your .env file. The code sample shows how to configure the plugin to load environment variables from a .env file located in a custom directory.

module.exports = {
  service: 'my-service',
  plugins: ['serverless-dotenv-plugin'],
  custom: {
    dotenv: {
      path: './config/.env'
    }
  },
  provider: {
    name: 'aws',
    runtime: 'nodejs14.x'
  },
  functions: {
    hello: {
      handler: 'handler.hello',
      environment: {
        MY_ENV_VAR: process.env.MY_ENV_VAR
      }
    }
  }
};

Multiple Environment Files

This feature allows you to use different .env files for different environments. The code sample demonstrates how to configure the plugin to load environment variables from different .env files based on the environment.

module.exports = {
  service: 'my-service',
  plugins: ['serverless-dotenv-plugin'],
  custom: {
    dotenv: {
      path: {
        development: './config/.env.development',
        production: './config/.env.production'
      }
    }
  },
  provider: {
    name: 'aws',
    runtime: 'nodejs14.x'
  },
  functions: {
    hello: {
      handler: 'handler.hello',
      environment: {
        MY_ENV_VAR: process.env.MY_ENV_VAR
      }
    }
  }
};

Other packages similar to serverless-dotenv-plugin

dotenv

dotenv is a popular package for loading environment variables from a .env file into process.env. It is widely used in Node.js applications but does not have built-in support for the Serverless Framework. You would need to manually integrate it into your serverless project.

serverless-secrets-plugin

serverless-secrets-plugin is another Serverless Framework plugin that helps manage secrets and environment variables. It integrates with AWS Secrets Manager to securely store and retrieve secrets. Unlike serverless-dotenv-plugin, it focuses on using AWS Secrets Manager rather than .env files.

serverless-env-generator

serverless-env-generator is a plugin that generates environment variables for your serverless project based on a configuration file. It provides more flexibility in generating environment variables but requires additional configuration compared to serverless-dotenv-plugin.

README

serverless-dotenv-plugin

Preload Environment Variables Into Serverless

Use this plugin if you have variables stored in a .env file that you want loaded into your serverless yaml config. This will allow you to reference them as ${env:VAR_NAME} inside your config and it will load them into your lambdas.

Install and Setup

First, install the plugin:

> npm i -D serverless-dotenv-plugin

Next, add the plugin to your serverless config file:

service: myService
plugins:
  - serverless-dotenv-plugin
...

Now, just like you would using dotenv in any other JS application, create your .env file in the root of your app:

DYANMODB_TABLE=myTable
AWS_REGION=us-west-1
AUTH0_CLIENT_ID=abc12345
AUTH0_CLIENT_SECRET=12345xyz

Plugin options

By default, the dotenv package will look for your .env file in the same folder where you run the command, but this can be customized by setting the path option. Also, be default, ALL env vars found in your file will be injected into your lambda functions. If you do not want all of them to be injected into your lambda functions, you can whitelist them with the include option.

custom:
  dotenv:
    path: ../../.env
    include:
      - AUTH0_CLIENT_ID
      - AUTH0_CLIENT_SECRET

Usage

Once loaded, you can now access the vars using the standard method for accessing ENV vars in serverless:

...
provider:
  name: aws
  runtime: nodejs6.10
  stage: dev
  region: ${env:AWS_REGION}
...

Lambda Environment Variables

Again, remember that when you deploy your service, the plugin with inject these environment vars into any lambda functions you have and will therefore allow you to reference them as process.env.AUTH0_CLIENT_ID (Nodejs example).

Examples

You can find example usage in the examples folder.