Kankyō

環境, かんきょう

An configurable and environment aware .env alternative.

• Getting started
  • Adding to your project
  • Installed globally
  • With npx
• Usage
  • From the command line
  • Programatically
  • Fron NPM scripts
• Environment file
• Generating the file
  • Default Variables
  • Configurable Environments
  • Options
    • Required fields
      • CI/CD
• String interpolation
• Full file example
• Cross-platform
• License

Getting started

Adding to your project

npm install --save kankyo

Installed globally

npm install -g kankyo

With npx

npx kankyo exec -- node app.js

Usage

From the command line

$> npx kankyo --help

Usage: cli [options] [command]

Options:
  -q --quiet          Quiet mode
  -e, --env <env>     Specify the environment manually
  -f --force          If set, will ignore schema/required fields mismatch
  -i, --input <file>  Specify the environment file
  -V, --version       output the version number
  -h, --help          display help for command

Commands:
  init
  exec
  help [command]      display help for command

By using the cli's exec command, followed by your own shell command, Kankyō will load the environment and run the specified command with it.

e.g

npx kankyo exec -- command arg1 arg2 arg3

Programatically

At the earliest stage possible, you can require Kankyō and call its inject method to load up the environment file into the current environment. As you would traditional .env files

e.g

require('kankyo').inject();

console.log(process.env);

Fron NPM scripts

Configure your scripts to run anything with Kankyo

{
  // ...
  "scripts": {
    "start": "kankyo exec -- node app.js"
  }
}

Environment file

Kankyo is configured using a custom TOML file

The default file name is .kankyo.toml

However it also supports the following names as alternatives:

• .kankyo.toml
• .environment.toml
• .env.toml
• kankyo.toml
• environment.toml
• env.toml

Generating the file

A file can be generated inside your project using the following command:

npx kankyo init

Default Variables

Start by setting the default variables of your environment

[defaults]

hostname      = "hello"
database_name = "my_db"

Configurable Environments

You can set any number of custom environments, here's an example of us setting a staging environment

[defaults]

# ...

[env.staging]

database_name = "my_staging_db"

When run in staging mode, the default database_name will be overridden by the value set under the staging block

Options

• env_var - Set the variable name that defines which environment is used. Defaults to NODE_ENV
• uppercase - If set, will uppercase all environment variable names. Defaults to true
• required - An array of variable names which must be provided

Required fields

Under the [options] block, you can add a list of required variables

e.g

[options]

required = ["API_KEY]

An exception will be raised if that variable is missing during runtime

> kankyo exec -- <your app>

  kankyo:info Kankyo environment file detected: .kankyo.toml +0ms
  kankyo:info Loading environment +1ms
  kankyo:error Missing environment variables: API_KEY +0ms

This forces users to either :

• Add the value to the file (either in defaults or in the environment)
• Add it to the shell environment

> API_KEY=123 kankyo exec -- <your app>

  hello world !

CI/CD

This feature is particularly useful when dealing with critical variables such as passwords, api keys.

Your CI/CD platform can fill in those keys during deployment, and the error message keeps developers aware when working locally.

String interpolation

Variables defined in the Kankyō file support string interpolation using the "${...}" format.

Example:

[defaults]

word_a    = "foo"
word_b    = "bar"
sentence  = "${word_a} ${word_b}"

Full file example

[options]

env_key     = "NODE_ENV"
uppercase   = true

[defaults]

word_a    = "foo"
word_b    = "bar"
sentence  = "${word_a} ${word_b}"

[env.production]

word_a = "hello"
word_b = "world"

Cross-platform

Kankyō is not limited to nodejs projects. The kankyo exec command can run any type of project

Example with Ruby:

Set the env_key option to desired key

[options]

env_key     = "RUBY_ENV"

# ...

and run your ruby project

RUBY_ENV=development kankyo exec -- ruby program.rb

License

MIT License

Copyright (c) 2021 Patrick R

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.