Environments

Creating and using Linc environments

Table of contents

What is an Environment

An environment is a set variables that can be injected into your FAB at runtime. These variables are injected into window.FAB_SETTINGS before the rest of your app code is executed, ensuring these variables will always be available by the time your app boots. Environment variables be used to override your production settings to handle things like:

  • Different API URLs for staging/testing/production backends
  • API keys for third-party services that might be different, such as testing/live payment integrations
  • Features that may be turned on or off depending on the environment

Creating Environments

Creating Environments is handled in the environments page on a Linc site:

app.linc.sh/sites/<SITENAME>/environments

environments 1
image of environments page on Linc

Here you can define an arbitrary number of environments and associated environment variables.

Our example site how-to-linc doesn't have any environments just yet, so let's go ahead and create one. We'll create a new environment by clicking the Add new environment button and naming our new environment STAGING:

environments 2
Image of environment name UI on Linc

Let's set some variables on our environment. Click the Add settings button. Enter a name of BG_COLOR and a value of tomato then hit the save button:

environments 3
image of environment with one row of settings

Using Environments

With our STAGING environment set up, let's modify our how-to-linc project to generate FABs that can use this environment. We're going to try and use the value of BG_COLOR from our STAGING environment to override the default background color of our app.

Let's begin by creating a new file called config.js in the src directory with the following contents:

const lookupEnvVar = name => {
  if (typeof window.FAB_SETTINGS === 'object') {
    return window.FAB_SETTINGS[name]
  }
}

export default {
  BG_COLOR: lookupEnvVar('BG_COLOR') || 'darkmagenta',
}

We've added a helper method lookupEnv to pull a given environment variable out of FAB_SETTINGS if it exists.

Next, let's import config into App.js in the src directory, and use it to set the background colour of our app.

import React, { Component } from 'react'
import logo from './logo.svg'
import './App.css'
+ import config from './config'

class App extends Component {
  render() {
    return (
      <div
+        style=
+          backgroundColor: config.BG_COLOR,
+        }}
        className="App"
      >
        <header className="App-header">
          <img src={logo} className="App-logo" alt="logo" />
          <p>
            Edit <code>src/App.js</code> and save to reload.
          </p>
          <a
            className="App-link"
            href="https://reactjs.org"
            target="_blank"
            rel="noopener noreferrer"
          >
            Learn React
          </a>
        </header>
      </div>
    )
  }
}

export default App

We should make sure to delete the background color property from the App-header class in src/App.css while we're at it:

.App-header {
-  background-color: DarkMagenta
  min-height: 100vh;
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  font-size: calc(10px + 2vmin);
  color: white;
}

We'll commit the above changes to a new branch called linc-environments-demo and push the branch up.

Next, let's navigate to the site overview page for how-to-linc. Our new linc-environments-demo should now be visible. Let's go ahead and click on the new commit row for the branch:

clicking commit
Clicking a commit row

This will take us to the commit overview page. Once the commit has been successfully built and deployed, Linc should render some preview links in the header of the commit overview:

preview links 1
image of commit preview links

Here we have two different preview links of the same FAB: production, where only the FAB production settings (if any) are injected into the FAB, and staging, where the STAGING environment variables are injected into the FAB along side production settings.

If we view the production preview link, we can see that the app background is still DarkMagenta.

https://how-to-linc-a9b8e2943-production.linc-preview.sh/

how to linc production
image of production preview link

If we view the staging preview link, we can see that the app background color has changed to tomato.

https://how-to-linc-a9b8e2943-staging.linc-preview.sh/

how to linc staging
image of staging preview link

Hooray! It looks like our new FAB is using our STAGING environment variables. So long as our app keeps using the BG_COLOR variable from the STAGING environment, we can freely change the value of BG_COLOR on the environments page to whatever we like and our FAB will simply use whatever value it receives.

Let's take this demo one step further and create a new environment called DEVELOP. We'll give the environment a BG_COLOR variable with the value of SpringGreen:

environments 5
image of develop environment

If we go back to the commit overview for our last commit on the linc-environments-demo branch, we should see that a new preview link is available to us:

preview links 2
image of preview links with develop environment

If we view the develop preview link, we can see that the app background has now changed to SpringGreen.

https://how-to-linc-a9b8e2943-develop.linc-preview.sh/

how to linc develop
image of preview links with develop environment

This demonstrates that we can make as many new environments as we like and still run them against any of our old FABs.

Environments and Auto Deployments

It's time to merge the linc-environments-demo branch. Let's open a pull request.

Linc bot will automatically comment on the open pull request:

pr flow multiple environments
image of Linc bot comment on Github PR with multiple environment links

Linc bot's comment contains links to three separate deployments of the FAB generated from the head commit of the linc-environments-demo branch. One deployment each for our DEVELOP and STAGING Linc environments and one production deployment.

By default, Linc bot will include a deployment in it's pull request comment for every Linc environment you've created on a site. You can prevent automatic generation of deployments from Linc environments by un-checking Auto deployments on an environment:

no auto deployments
image of auto deployments toggle on Linc environment

The next time you make a commit, Linc bot will not include a deployment for the unchecked environment.

This guide covers the basics of setting up Linc environments. In the next section Releasing, we'll cover setting up deployment configuration to enable automatic releases of FABs.

Back to docs index