clinical:env

v3.1.7Published 8 years ago

This package has not had recent updates. Please investigate it's current state before committing to using it in your project.

clinical:env

An environemnt variable based replacement of Meteor.settings which exposes process.env on both server and client. Supports .env files and a twelve-factor app application architecture.

build status

========================================

Installation

meteor add clinical:env

========================================

Environment Config Files

You can create a .env file in the root directory of your project, which acts somewhat like an application specific bash_profile file. Simply add the environment variables you want for the app, as if you were specifying export or setenv commands. A sample .env file might look something like this:

  DEBUG=true
  TRACE=false
  DOMAIN=http://www.foo.com
  METEOR_ENV=development
  SECRET_KEY=ao8v7d8c8vcdi98vekd

========================================

Server Usage

Server usage is fairly straightforward, with all the environment variables being exposed through process.env. There are a number of helper functions, such as isDevelopment and isTesting and Env.display() which provide a rich programming API for environemnt-aware applications.

1  var secret_key = process.env.SECRET_KEY;  
2
3  Meteor.startup(function(){
4    console.log("Starting up " + process.env.DOMAIN + " in " + process.env.METEOR_ENV);
5
6    if(process.env.DEBUG){
7      Env.display();
8    }
9
10    if(Env.isDevelopment){
11      console.log("Logged in user is: " + Meteor.userId());
12    }
13  });

For environment variables to be exposed on the client, you have to explicitly opt-in by using the Env.allow() function.

1  Env.allow({
2    DEBUG: true,
3    TRACE: true,
4    METEOR_ENV: true,
5    DOMAIN: true,
6    SECRET_KEY: false
7  });

========================================

Client Usage

The client API is mostly isomorphic to the server, with variables being exposed on process.env, and all the same helper booleans available.

1  if(process.env.METEOR_ENV){
2    console.log("Running in " + process.env.METEOR_ENV);
3  }
4  if(Env.isDevelopment){
5    console.log("Logged in user is: " + Meteor.userId());
6  }
7  if(process.env.DEBUG){
8    Env.display();
9  }

You can also use the API within templates, like so:

1<template name="foo">
2  <span>Some lorem ipsum...</span>
3  {{#if isDevelopment}}
4    <span>This is Development!</span>
5  {{/if}}
6</template>

========================================

API

The complete API appears below.

Env.display()

Function, Anywhere

Env.variables()

Function, Anywhere

Env.allow(envObject)

Function, Server

Env.isProduction

Boolean, Anywhere

Env.isDevelopment

Boolean, Anywhere

Env.isTesting

Boolean, Anywhere

Env.isTraining

Boolean, Anywhere

Env.isStaging

Boolean, Anywhere

Env.isDebug

Boolean, Anywhere

Env.isTrace

Boolean, Anywhere

{{#if isProduction}}

Spacebars, Client

{{#if isDevelopment}}

Spacebars, Client

{{#if isTraining}}

Spacebars, Client

{{#if isStaging}}

Spacebars, Client

{{#if isDebug}}

Spacebars, Client

========================================

Environment Precedent

We can specify environment variable in a few different ways (which is exactly why environment variables are so handy); each with a different precedent.

####1. Environment Profile
The most insistent way to define the variable. Will override any other setting.

nano ~/.profile
  METEOR_ENV="development"

2. Export Variable

As insistent as setting the variable in the ~/.profile file, but is temporary to the shell session.

export METEOR_ENV="staging"

3. Inline Variable

Probably the most convenient way of specifying an environment variable; particularly for debugging and development purposes. Setting an inline variable will override a .env file, but will be ignored if the variable has been specified in ~/.profile or defined via export.

METEOR_ENV="testing" meteor -p 4000

4. .env Variable

The .env file is similar to ~/.profile, but is application specific. Think of it as a way to mix-and-match a ~/.profile file on a per-app basis.

METEOR_ENV="dev"

Node Over Meteor

NODE_ENV takes precedent over METEOR_ENV

========================================

Should I commit my .env file?

Try not to commit your .env file to version control. It is best to keep it local to your machine and local on any machine you deploy to. Keep production credential .envs on your production machines, and keep development .envs on your local machine.

Also, beware environment variables that have been sent to the client, and which wind up getting stored in cache. You may need to debug using incognito mode.

========================================

Acknowledgements

This package is a mashup and synthesis of a number of other packages.

pauldowman:dotenv mrt:environment-hooks mrt:allow-env panphora:environment-template-helpers jboulhous:dev

A big shout out to Mike Bannister, Tom Wijsman, Paul Dowman, David Miranda, Neil MacMunn, Jamal Boulhous, Gadi Cohen, and Arunoda. This package wouldn't have happened without their work.

========================================

Testing

When running tests, make sure to specify the METEOR_ENV environment variable!

1METEOR_ENV=development meteor test-packages clinical:env

========================================

Licensing

MIT. Use as you will.