Table of contents

• What are run-time environment variables?
• Creating run-time environment variables
• Using run-time Environment Variables
• Environments and Auto Deployments

What are run-time environment variables?

Run-time environment variables are 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 can be used to override your FAB 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 run-time environment variables

Creating run-time environment variables is handled in the environments page on a Linc site:

‍Site Overview > Environments

Here you can define an environment; a collection of environment variables.

Our example site environments-demo 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:

Now let's add some variables to our environment by clicking the Add settings button.

We'll define a variable with the name of BG_COLOR and a value of the CSS colour tomato, then click the Save button:

Now that we have a new environment set up, let's jump over to the site overview for the environments-demo site:

In the Recent Commits section under the previews column, we can see a new preview link has appeared with the characters St, short for STAGING.

This link leads to the following URL:

https://environments-demo--488e3dec8--staging.linc-preview.sh/

Let's have a closer look at the structure of this URL:

Here, we can see that our new preview link consists of three components: a site name, a Bundle ID and the name of an environment.

This URL pattern lets Linc's preview infrastructure know that we want to preview the bundle 488e3d3c8 from our site environments-demo in our STAGING environment.

Let's open this preview URL in a new tab. The variables we defined on the STAGING environment, in this case, just BG_COLOR, will be automatically injected into our app under window.FAB_SETTINGS. We can prove this by jumping into the browser console and logging out window.FAB_SETTINGS:

Now that our variable BG_COLOR is being injected into our app, we need to alter our application source code so that it can use this, and indeed, any other environment variables at run-time.

Using run-time environment variables

With our STAGING environment set up, it's time to modify our environments-demo project so that it can pull environment variables out of the window object at runtime.

The aim here is to use the BG_COLOR variable from our STAGING environment to override the current default background colour of our app:

We'll start by creating a new file called config.js in our project src directory with the following contents:

--CODE:language-js--
const lookupEnvVar = (name) => {
 if (typeof window.FAB_SETTINGS === "object") {
   return window.FAB_SETTINGS[name];
 } else {
    // Note: some build systems (like Create React App) only expose
    // process.env vars that start with a prefix (like REACT_APP_)
   return process.env[`REACT_APP_${name}`];
 }
};

const config = {
 BG_COLOR: lookupEnvVar("BG_COLOR"),
};

export default config;

In the above snippet, we've added a helper method lookupEnv to pull environment variables out of window.FAB_SETTINGS if it exists, or out of process.env if not.

Now let's import our new config into our App.js file and use it to override the background colour of our app:

--CODE:language-diff--
import logo from "./logo.svg";
import "./App.css";
+ import config from "./config";
‍
+ const APP_BG_COLOR = config.BG_COLOR || "#282c34";

function App() {
 return (
+    <div style={{ backgroundColor: APP_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;

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

--CODE:language-diff--
.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 add-environments-config and push the branch up. Our new branch should appear in the Linc UI and start building. Once the new commit has finished building, we can now test out our changes by clicking the STAGING preview link:

https://environments-demo--8e5cb7686--staging.linc-preview.sh/

Opening the STAGING preview link reveals that our app background colour has been set to tomato.

‍It looks like our app is successfully pulling the BG_COLOR variable out of window.FAB_SETTINGS. Let's take this demo one step further and create a new environment called DEVELOP.

Just like the STAGING environment, we'll define a variable with the name of BG_COLOR, only this time we'll use a value of the CSS colour royalblue:

Heading back to the Overview for our environments-demo site, we can now preview all of our changes in the DEVELOP environment:

Let's open a preview from the add-environments-config branch in the DEVELOP branch:

https://environments-demo--8e5cb7686--develop.linc-preview.sh/

Here, we can see that the app background has now been set to royalblue.

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 for a particular environment by un-checking the Auto deployments checkbox on your environment of choice:

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.

‍