@hedviginsurance/embark
v3.1.0
Published
Embark is Hedvigs framework for creating forms and user stories.
Downloads
164
Keywords
Readme
Embark
Embark is Hedvigs framework for creating forms and user stories.
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) 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.
2. Embark Server
Embark Server is responsible to serve Embark flows so Embark Clients like 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 folder. Its implementation can be found inside 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. For the content editor's documentation - see embark editor docs.
Getting Started
Prerequisites
Install Node with nvm
While one can install node
by downloading it from their official website 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:
- Install
nvm
https://github.com/creationix/nvm nvm install
(installs the node version specified in.nvmrc
)nvm use
(use version from.nvmrc
)
Install Yarn v1
In order to instal yarn
just follow their official installation steps
Install dependencies
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
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
- 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
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 project ready in your machine. Check Angel - Getting Started for more details.
- Run Angel locally
cd <path-to-Angel-repo>
yarn watch
- Run Embark locally
cd <path-to-embark-repo>
yarn watch
- Access Angel locally by going into http://localhost:8080/ and load the desired flow in development mode.
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 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:
- Have cloned
prod-env
repository; - Have an AWS account configured by following this guide
Having met the prerequisites and after having deployed on staging and verfied your changes all you need to do is:
cd
to theprod-env
repo- Run help me to deploy script:
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 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 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
- Check out the PR branch and update