Linc allows you to build your frontend project on an external CI platform & upload the resulting build artefact to Linc.
This means you don't have to ditch your existing CI service to enjoy the benefits of Linc, such as shareable preview URLs and automated releases to world class edge hosting providers.
Here's how to get started:
Create a site
The first step to using Linc with external CI is to create a new Linc site.
Navigate to the Site Creator page in the Linc interface. You can get there by jumping into your Sites page and clicking the New Site button in the top right corner:
Once you're at the Site Creator page, you will be prompted to select where your application is hosted:
Select the Other option. Then, in the provided Sitename field, give your site a short and memorable name and click Next:
This will take you to the final step (and optional) step - Production Releases:
For now, select the None option and click the Create site button. You can always add production release config to your site later on.
You'll be redirected to your new Site Overview:
Now that your site is created, the next step is to configure your project to compile to a FAB (Frontend Application Bundle).
Configure your app
Linc's preview and deployment infrastructure is built on top of the Frontend Application Bundles (💎 FABs) specification. FAB is a bundle format for frontend applications.
They unify static sites, single page applications (SPAs), server-side rendering (SSR) & server-side logic in a single format, one that is universally compatible with and easy to deploy to a wide range of hosting providers, including your own infrastructure.
To upload build artefacts to Linc, first, you must your project to compile to the Frontent Application Bunlde format.
Run the following command in your project:
npx fab init
This will download and run the FAB auto-configure utility in your project directory. The utility will try to detect your project type and then install the necessary FAB packages required to compile your project source code to the FAB format:
The auto-configure utility will also add a configuration file called fab.config.json5 where you can customise how your FABs are compiled.
Lastly, three scripts will be added to your project package.json:
+ "build:fab": "npm run build && npm run fab:build",
+ "fab:build": "fab build",
+ "fab:serve": "fab serve fab.zip",
With this configuration, your project should now be able to compile to the FAB format.
The next and final step is to upload FABs to Linc.
Uploading to Linc
Linc provides an NPM package fab-upload-cli allowing you to FABs from your CI pipeline directly to Linc.
You can install fab-upload-cli as a development dependency in your frontend project via Yarn or NPM:
yarn add --dev @bitgenics/fab-upload-cli
npm install --dev @bitgenics/fab-upload-cli
Once the package has been installed, add the following script to your package.json:
"build:fab": [your existing step to generate a FAB],
+ "fab-upload": "fab-upload"
When the fab-upload script is run with either npm run fab-upload or yarn fab-upload, it runs the fab-upload-cli package installed above.
The fab-upload-cli package will then attempt to compile a new FAB by running the build:fab script added by the FAB auto-configure utility also defined your package.json.
After running the build:fab, fab-upload-cli will attempt to upload the resulting FAB artefact to Linc, as well as the command line output of the build:fab script. It will also upload some extra commit data used to populate your site in the Linc interface with commit and build information, as well as to generate and deploy preview URLs.
In order for fab-upload-cli to upload a FAB and this data to Linc, it requires two environment variables be set:
LINC_SITE_NAME - The name of your Linc site.
LINC_API_KEY - An API key obtained from Linc.
Your Linc site name can be found on the overview page for your Linc site:
Copy your site name and use it as the value of LINC_SITE_NAME in your CI service.
Your Linc API key can be found by navigating to your site overview:
Your API key can also be found found in your settings:
Site > Settings > Build > External CI
Copy the API key and set it as the value of the LINC_API_KEY environment variable in your CI service.
With both the LINC_SITE_NAME and LINC_API_KEY environment variables set in your CI service, you can start using fab-upload-cli.
If you encounter any problems while using fab-upload-cli, raise an issue here or contact us at: