npm package: @hedviginsurance/embark
Description: Embark is Hedvigs framework for creating forms and user stories.
Latest version: 3.1.0

# Embark

Embark is Hedvigs framework for creating forms and user stories.

<img style="max-width: 800px;" src=".github/assets/embark-flow-sample-ui.png" alt="Embark story sample" />

# Core concepts

## 1. Embark flow

_Embark flows_ describe forms used to get users necessary data during the onboarding process. They consist on a number of steps (a.k.a [passages](https://hedviginsurance.github.io/embark-docs/docs/what-is-passage)) presented in a question/answer manner with transitions from one to another in a non linear way, meaning that the next step might depend on users previous answer. _Embark flows_ are created with the assistence of a tool called [Angel](https://github.com/HedvigInsurance/Angel).

<img style="max-height: 600px;" src=".github/assets/embark-flow-sample.png" alt="Embark flow Sample" />

## 2. Embark Server

_Embark Server_ is responsible to serve _Embark flows_ so _Embark Clients_ like [`web-onboarding`](https://github.com/HedvigInsurance/web-onboarding) and ios/android apps can access them.

## 3. Embark Client

An _Embark Client_ is responsible to access and display _Embark flows_.

# What's inside?

This repository holds three things:

- The implementation for the _Embark Server_. It simply consists on web server that exposes all the _Embark Flows_ placed under [angel-data](./angel-data) folder. Its implementation can be found inside [server.ts](./server.ts) file.
- The implementation of the _Embark Client_ for the web: _Embark Client Web_. It consists on a set of _React_ components and hooks.
- A small _React_ app used for previewing while developing _Embark Flows_ with our custom tool: _Angel_. It's exposed via _Embark Server_ under `/client.js` endpoint. More info about _Angel_ can be found in its [repository](https://github.com/HedvigInsurance/Angel). For the content editor's documentation - see [embark editor docs](https://hedviginsurance.github.io/embark-docs).

# Getting Started

## Prerequisites

- [`node`](https://nodejs.org/en/)
- [`yarn v1`](https://classic.yarnpkg.com)

### Install Node with nvm

While one can install `node` by downloading it from their [official website](https://nodejs.org/en/download/) we recomend do it through `nvm` which is a tool that you can use to easily install and manage multiple `node` versions in your machine:

1. Install `nvm` [https://github.com/creationix/nvm](https://github.com/creationix/nvm)
2. `nvm install` (installs the node version specified in `.nvmrc`)
3. `nvm use` (use version from `.nvmrc`)

### Install Yarn v1

In order to instal `yarn` just follow their [official installation steps](https://classic.yarnpkg.com/en/docs/install)

### Install dependencies

```sh
yarn install # or simply yarn
```

# Development

## Embark Server

You probably will not be doing changes on the _Embark Server_. In any case, you can run it locally by executing

```sh
yarn start
```

> Observe tho that it doesn't count with live reload so you would need to restart it for it to pick up any changes added after having it started.

## Embark Client Web

There are a couple of options to choose for the development of _Embark Client Web_. The most suitable will depend on the nature of the changes you intend to insert:

- If you want to add/update UI components used for displaying _Embark flows_ in a isolated way, you probably want to use [_Storybook_](https://storybook.js.org/)
- If you want to add/update code related with _Embark flows_ processing and/or verify your changes in the context of the whole flow, the best option would be run your flow locally with _Angel_

### Developing with _Storybook_

To start _Storybook_ just run

```sh
yarn storybook
```

and then access http://localhost:6010/. If your components are not _Storybooked_ yet make sure to first _storybookify_ them.

### Developing with _Angel_

Make sure you have the [Angel](https://github.com/HedvigInsurance/Angel) project ready in your machine. Check [Angel - Getting Started](https://hedviginsurance.github.io/embark-docs/docs/what-is-angel#getting-started) for more details.

1. Run _Angel_ locally

```sh
cd <path-to-Angel-repo>
yarn watch
```

2. Run _Embark_ locally

```sh
cd <path-to-embark-repo>
yarn watch
```

3. Access _Angel_ locally by going into http://localhost:8080/ and load the desired flow in [_development mode_](https://hedviginsurance.github.io/embark-docs/docs/what-is-angel/#story-format).

With that done, any recent changes related with _Embark Client Web_ code will be taken into account while previwing _Embark flows_ in _Angel_.

# Deploy

## Embark Server

The _Embark Server_ is dockerized and it is hosted on Hedvig's _AWS_ plataform.

### Staging

All you need to do to deploy _Embark Server_ on staging is to merge your changes into `master` and wait for _Codefresh_ to build the docker container. A message will be sent to [#platform-deploy](https://hedviginsurance.slack.com/archives/C01PGTP0VK4) when the deployment process is finished.

### Production

In order to deploy _Embark Server_ on prod you'll need to use the `prod-env/bin/help_me_deploy.py` script; so make sure you:

1. Have cloned [`prod-env`](https://github.com/HedvigInsurance/prod-env) repository;
2. Have an _AWS_ account configured by following [this guide](https://www.notion.so/hedviginsurance/AWS-Central-Login-baa414cff38242669ee7f6d54dc1820f)

Having met the prerequisites and after having deployed on staging and verfied your changes all you need to do is:

- `cd` to the `prod-env` repo
- Run _help me to deploy_ script:

```sh
export AWS_PROFILE=dev
bin/help_me_deploy.py prod
```

- Choose `embark` as the service you want to deploy
- ...and follow the instructions. At some point you will be presented with a link to the diff between the commit you want to release vs. what's currently deployed in production. It's a good idea to look through all changes before proceeding with the deploy. You can follow the progress in the [#platform-deploy](https://hedviginsurance.slack.com/archives/C01PGTP0VK4) Slack channel.

## Embark Client Web

The _Embark Client Web_ is distributed as a NPM package. It is published via a GitHub Action workflow to NPM.

Steps:

- Go to the [Publish to NPM](https://github.com/HedvigInsurance/embark/actions/workflows/publish-npm.yml) under the "Actions" tab.
- Trigger a new run with the version you want to publish, e.g. "4.2.1"
- A PR is created for you so that you can merge the new version to the `master` branch
  - Check out the PR branch and update `CHANGELOG` with your changes