Wondering what’s next for npm?Check out our public roadmap! »

    kankyo
    TypeScript icon, indicating that this package has built-in type declarations

    1.6.1 • Public • Published

    Kankyō

    環境, かんきょう

    An configurable and environment aware .env alternative.

    forthebadge forthebadge

    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.

    Install

    npm i kankyo

    DownloadsWeekly Downloads

    17

    Version

    1.6.1

    License

    ISC

    Unpacked Size

    599 kB

    Total Files

    34

    Last publish

    Collaborators

    • avatar