Getting Started

Configuring a repository and the basics of using Linc

This guide teaches you how to configure a repository to output FABs and the basics of using Linc, including:

  • Creating a Linc Site
  • Generating preview links
  • Linc & Github Pull Request flow

This guide assumes you already have a Linc account. If you do not have a Linc account you can create one here.

Table of contents

Prerequisites

To start using Linc, please ensure you have:

  • Owner permissions for a repository hosted on Github

Configuring your repository

The first step to getting your repository working on Linc is to configure it to output a FAB or Frontend Application Bundle.

FABs, or Frontend Application Bundles are a compile target for frontend applications. They provide portability between various build tool-chains like create-react-app, Gatsby and Next.js and runtime environments like AWS Lambda, CloudFlare Workers, NodeJS and more. This allows for decoupling of your code and your configuration letting you run the same code against multiple backends.

Let's begin by creating a simple demo app using create-react-app:

npx create-react-app how-to-linc
cd how-to-linc

With our app up and running, we'll go ahead and install @fab/static as a development dependency:

yarn add --dev @fab/static
npm install --dev @fab/static

Next, add a couple of scripts to your package.json:

  "scripts": {
    "build": "[your existing build step]",
+   "build:fab": "npm run build && npm run fab:compile",
+   "fab:compile": "fab-static [dirname]",
  },
}

NOTE: Replace dirname with wherever your built files live (build for Create React App & friends, public for Gatsby, dist for some others)

We've added two scripts here, fab:compile which runs the fab-static builder, and build:fab that builds the project first. Most of the time, and especially when you're using a FAB-enabled platform like Linc, you'll mostly run build:fab, but having a separate fab:compile step can be handy as you set things up.

You can test it out by running:

npm run build:fab

Once this is complete, you should have a fab.zip file (and a .fab directory with a bunch of build files). Those don't need to be checked in to your repository, so you can add them to your .gitignore file with this one-liner:

echo "
.fab
fab.zip" >> .gitignore

If you want to spin up your fab.zip file locally, you can use @fab/serve. You can either install it globally:

yarn global add @fab/serve
npm install --global @fab/serve

fab-serve fab.zip

Or use the awesome npx (which is bundled with NodeJS) to run a command-line NPM package without needing to install it:

npx @fab/serve fab.zip

You should see your app running on http://localhost:3000!

Note: this process will add one file fab.zip and one directory .fab into your project.

With your app correctly configured, make sure to commit and push your changes.

Creating a site

Now that your repository is correctly configured, jump over to the Create a site page on Linc. Here you can create a new frontend project or Site from your repository.

Select your repository from the list of available repositories:

new site 1
create new Linc site - part 1

If you can't find your repository, you may need to update your Linc Installation to include the missing repository.

Once you select a repository, you will be redirected to a partially pre-filled form:

new site 2
create new Linc site - part 2
Here, you can specify your repository's release branch as well as the file path to the repository's package.json. By default, Linc assumes the repository's release branch is master and that the package.json is located at the root of your project: /package.json. Feel free to override these values to whatever you like.

Once you're done, go ahead and give your site a name. Site names are used in preview links, so it's advisable to pick something fairly short and memorable.

Go ahead and click save. You will be redirected to the site overview page for your newly created site:

site overview 0
site overview

Make a commit

Now that our site is set up, new commits to our site will automatically appear under the Recent Commits section of our site overview page. Linc automatically attempts to generate a FAB from a new commit and deploy the FAB to shareable preview links.

Let's see this in action by creating a new branch on our how-to-linc repository called linc-setup-demo.

Edit the background color of App-header in src/App.css to DarkMagenta:

.App-header {
- background-color: #282c34;
+ background-color: DarkMagenta;
  ...
}

Commit this change to the linc-setup-demo branch with the message 'Change header color to dark magenta', then push the branch up to your remote repository.

The site overview should now live update with a new commit:

site overview first commit
site overview - first commit

After a few minutes, Linc has generated a FAB from the new commit and deployed it to a preview link:

site overview first commit success
site overview - first commit success

Click the blue preview link icon to view a live preview of the commit, or click here:

first commit
preview link - first commit

Looks good! Now that we're confident with the change, let's open a pull request in Github to merge the linc-setup-demo branch.

Merge commit into release branch

Once the pull request is open Linc bot will automatically post a comment to the pull request page:

pull request linc integration
preview link - first commit

Here, Linc bot's comment includes direct links to the preview deployment we just viewed, making it easy for reviewers to preview the changes for themselves.

Merge the branch and jump over your Linc site overview:

post merge
preview link - first commit

We can see linc-setup-demo has been successfully merged into master (our designated release branch), and now we now have an active release as well because commits to our release branch are automatically released. Our site doesn't have any deployment configuration yet so right now our FAB is only being released to a Linc trial domain like the following:

<SITENAME>.linc-trial.sh

To learn more about setting up deployment configuration, see the Releasing page.

This section covered the basics of configuring a frontend repository to output FABs, creating a Linc Site from a configured repository, and the basic flow around generating and previewing FABs with Linc.

In the next section we'll cover setting up and using Environments.

Back to docs index