Set up tutorial environment

Introduction

This document describes how to set up your environment and install the necessary software for running the Tutorial projects on this site.

Audience

Developers that want to try out the Tutorial projects.

Prerequisites

None.

Not included

Credentials, such as a License API Key. This is provided to you by Colibrio when you get access to the framework.

Installing necessary software

In order to get and run the Tutorials, you need to have the following software on your machine:

Git
NodeJS
Yarn (optional)

Installing Git

You need the Git version control software in order to get the source code for the Tutorials.

Check if you have Git installed by running the following command in a terminal:

NONE

git --version

If you don't have Git installed, please follow a Git install guide like for example:

Installing NodeJS

You need NodeJS in order to build the Colibrio Tutorial projects.

Check if you have NodeJS installed by running the following command in a terminal:

NONE

node --version

If you don’t have NodeJS installed, you can find various install alternatives from the official NodeJS website https://nodejs.org/ . We recommend to use the latest LTS version of NodeJS.

Installing Yarn (optional)

You need Yarn or NPM in order to download and install NPM packages that the Tutorial projects depend on. When you install NodeJS you also get the NPM installed by default. If you want to use Yarn instead, install Yarn Classic as described on the official website: https://classic.yarnpkg.com/en/docs/install

Cloning the Tutorials Git repository

The source code for the tutorials is available in a public Bitbucket Git repository. Run the following command line to create a local copy of the repository into the directory colibrio-web-framework-tutorials:

NONE

git clone https://bitbucket.org/colibrio/colibrio-web-framework-tutorials.git colibrio-web-framework-tutorials

Building and running a tutorial project

If you navigate into colibrio-web-framework-tutorials you should see several directories. Each directory is a tutorial project that you can build and run.

You need to perform the following steps in a tutorial project to build and run it:

Add your Colibrio NPM Auth Token to the project’s .npmrc file.
Add your Colibrio License API Key to the project’s .env file.
Run yarn or npm install to install project dependencies.
Run yarn start or npm run start to build the project and start a server on http://localhost:1234.
Navigate a web browser to http://localhost:1234.

Configuring .npmrc with an NPM Auth Token

The @colibrio/colibrio-reader-framework NPM package is hosted in a private NPM registry. To be able to download it as a dependency with yarn or npm, you need to configure the project’s .npmrc file.

Create an .npmrc file in the project with the following content:

CODE

@colibrio:registry=https://npm.pkg.colibrio.com/
//npm.pkg.colibrio.com/:_authToken=<authToken>
//npm.pkg.colibrio.com/:always-auth=true

Replace <authToken> with the NPM Auth Token you received from Colibrio.

Configuring .env with a License API Key

When you build a tutorial project, it expects the environment variable COLIBRIO_LICENSE_API_KEY to contain your Colibrio License API Key. By creating an .env file, you can define environment variables that are loaded while building the tutorial project.

Create an .env file in the project with the following content:

CODE

COLIBRIO_LICENSE_API_KEY=<apiKey>

Replace <apiKey> with the License API Key you received from Colibrio.

Installing project dependencies

Each tutorial project declares a list of dependencies in the package.json file that are required to develop, build and run the project.

Install dependencies using Yarn
NONE
```
yarn install
```
Install dependencies using NPM
NONE
```
npm install
```

This will install support for Typescript in the project and Parcel which is used to build and serve the tutorial as a web app.

If the @colibrio/colibrio-reader-framework dependency fails to install, make sure you have configured the .npmrc file.

Running the project

Every tutorial project declares a “start” script in the package.json file that builds the corresponding tutorial project and serves it as a web app on http://localhost:1234

using Yarn:
NONE
```
yarn start
```
using NPM:
NONE
```
npm run start
```

The “start” script uses parcel serve to build and host the tutorial. It will watch for source file changes and automatically rebuild the web app if needed.

You can pass additional options to parcel serve. For example, change the port used to 8899:

CODE

yarn start -p 8899

Please refer to https://parceljs.org/features/cli/#parameters for all available Parcel options.