Environments

🚧 docs under construction 🚧

Table of contents

• What is an environment?
• Creating Environments
• Using Environments
• Environments and Auto Deployments

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

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:

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:

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:

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:

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/

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/

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:

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:

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/

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:

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 unchecking Auto deployments on an 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 seting up deployment configuration to enable automatic releases of FABs.