npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

serverless-env-generator

v1.4.1

Published

A Serverless 1.x plugin to automatically create a .env file during deployment by merging environment variables from one or more YAML files. Variables can be securely encrypted with KMS. Multiple stages and profiles are supported.

Downloads

116

Readme

Serverless Env Generator Plugin

License NPM Build Status Requirements Status Coverage Status

This plugin automatically creates a .env file during deployment by merging environment variables from one or more YAML files. During runtime these variables can then be loaded into process.env using dotenv.

For a brief introduction, read our blogpost about introducing serverless-env-generator.

Key features:

  • Support for multi-stage configurations and custom profiles
  • Value of environment variables can be encrypted with AWS KMS, allowing teams to manage sensitive information in git.
  • By using KMS, access to secrets can be controlled with IAM. We recommend to create one KMS key per serverless-profile, so you can limit access to credentials to deployment privileges.
  • During deployment a temporary .env file is created and uploaded to Lambda by merging and decrypting values of your environment YAML files.
  • Environment variables can be loaded with dotenv at startup in Lambda without delays from KMS.
  • Supports serverless-local-dev-server and serverless offline for local development.

Notes

Please note that the uploaded .env file contains secrets in cleartext. Therefore we recommend to use Serverless Crypt for critical secrets. This tool aims to strike a balance between storing secrets in plaintext in Lambda environment variables and having to decrypt them at runtime using KMS.

Furthermore the tool does not support environment variables generated by Serverless. We recommend to set these variables directly in each functions configuration in serverless.yml.

When used with serverless-local-dev-server your environment variables are directly loaded into process.env. No .env file is created to make sure that your local development and deployment tasks do not interfere :-)

This package requires node >= 8.0. Due to the reliance on KMS, encryption is only supported for AWS.

The .env.local file in the project root is here only for the tests.

Table of Contents

Requirements

Getting Started

1. Install the plugin and dotenv

npm install dotenv --save
npm install serverless-env-generator --save-dev

2. Create a key on KMS

See: https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html

Please make sure to create the KMS key in the same region as your deployment.

For aliases we recommend to use the service name, for administration privileges no user (your AWS account has full permissions by default) and for usage privileges "serverless-admin" to link access permissions to deployment permissions.

3. Add the plugin to your serverless configuration file

serverless.yml configuration example:

provider:
  name: aws
  runtime: nodejs8.10

functions:
  hello:
    handler: handler.hello

# Add serverless-env-generator to your plugins:
plugins:
  - serverless-env-generator

# Plugin config goes into custom:
custom:
  envFiles: #YAML files used to create .env file
    - environment.yml
  envEncryptionKeyId: #KMS Key used for encrypting values
    dev: ${env:AWS_KMS_KEYID} #Key used for development-stage

4. Add the .env file to your .gitignore

As the generated .env file contains the secrets in cleartext, make sure that it will never be checked into git!

.gitignore code example:

.env

5. Add variables to your environment YAML file

Command example:

serverless env --attribute name --value "This is not a secret"
serverless env --attribute secret_name --value "This is a secret" --encrypt

6. Write your function

Note that the .env file is automatically created when you deploy your function, so you can just load those variables with dotenv 🎉

Code example:

require('dotenv').config() // Load variables from .env file

module.exports.hello = (event, context, callback) => {
  const response = {
    statusCode: 200,
    body: JSON.stringify({
      message: process.env.secret_name,
      input: event
    })
  }
  callback(null, response)
}

7. Deploy & test your function

Command example:

serverless deploy
serverless invoke -f $FUNCTION_NAME

Result example:

{
    "body": "{\"input\": {}, \"message\": \"This is a secret\"}",
    "statusCode": 200
}

Commands

You can use these commands to modify your YAML environment files.

If no stage is specified the default one as specified in serverless.yml is used.

Viewing environment variables

Use the following commands to read and decrypt variables from your YAML environment files:

List variables

serverless env
serverless env --stage $STAGE

View one variable

serverless env --attribute $NAME
serverless env --attribute $NAME --stage $STAGE

#shorthand:
sls env -a $NAME
sls env -a $NAME -s $STAGE

Decrypt variables

serverless env --decrypt
serverless env --attribute $NAME --decrypt
serverless env --attribute $NAME --stage $STAGE --decrypt

#shorthand:
sls env -a $NAME --decrypt
sls env -a $NAME -s $STAGE -d

Setting environment variables

Use the following commands to store and encrypt variables in your YAML environment files:

Note that variables are stored to the first file listed in envFiles.

Set a variable

serverless env --attribute $NAME --value $PLAINTEXT
serverless env --attribute $NAME --value $PLAINTEXT --stage $STAGE

#shorthand:
sls env -a $NAME -v $PLAINTEXT
sls env --a $NAME -v $PLAINTEXT --s $STAGE

Set and encrypt a variable

serverless env --attribute $NAME --value $PLAINTEXT --encrypt
serverless env --attribute $NAME --value $PLAINTEXT --stage $STAGE --encrypt

#shorthand:
sls env -a $NAME -v $PLAINTEXT -e
sls env -a $NAME -v $PLAINTEXT -s $STAGE -e

YAML File Structure

Environment variables are stored in stage-agnostic YAML files, which are then merged into a .env file on deployment.

File example:

dev: #stage
    foo: bar #cleartext variable
    bla: crypted:bc89hwnch8hncoaiwjnd... #encrypted variable

production:
    foo: baz
    bla: crypted:ncibinv0iwokncoiao3d...

You can create additional YAML environment files, for example to include variables that are dynamically generated. Just add them to the envFiles in your serverless.yml.

Usage with the serverless-plugin-webpack

In case you are also using the serverless-plugin-webpack there are some caveats:

1. Plugin order in `serverless.yml'

You have to place serverless-env-generator before the serverless-plugin-webpack in the serverless.yml

# serverless.yml
plugins:
  - serverless-env-generator
  - serverless-plugin-webpack

2. Additional dotenv-webpack

You need to have the dotenv-webpack plugin installed:

npm install dotenv-webpack --save-dev

and configured:

// webpack.config.js
const Dotenv = require('dotenv-webpack')
module.exports = {
  // ...
  plugins: [
    // ...
    new Dotenv()
  ]
}

Contribute

Anyone is more than welcome to contribute to the serverless-env-generator plugin. Here just a few things to consider when doing so:

  • this project uses yarn as a package manager
  • make sure to pass all tests (run yarn test)
  • you can add your local serverless-env-generator version to other projects: yarn add --dev file:/../serverless-env-generator

License & Credits

Licensed under the MIT license.

Created and maintained by DieProduktMacher.

Inspired by Serverless Crypt.