Bearer

The Bearer Documentation Hub

Welcome to the Bearer documentation hub. You'll find comprehensive guides and documentation to help you start working with Bearer as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Changelog

Scenario Anatomy

Bearer is a highly opinionated framework that lets developers easily build and run Integration Scenario.

Understanding the core anatomy of a Scenario is key in order to make the most of Bearer and keep-up with the promise of building highly re-usable and plug and play Scenario.

Component Structure

A Scenario act as a gate between a host app and a 3rd party Service API. To make Integration of a Scenario easy, Bearer relies on components that can be integrated as custom HTML tags, known as WebComponents. Those components are created using the @RootComponent() decorator.

By default, Scenarios are created with two Root Components called action and display belonging to a group called feature. A Scenario can use as many Root Components and group as needed. At least one Root Component is needed.

Root Components can share data by storing & retrieving State using a referenceId (more on that below).

When Scenario are created using an API Authentication mechanism, Bearer dynamically provides a setup group of Root Components.

Every Root Component end-up being served as a WebComponent, the HTML tag associated is generated using: <ScenarioName-RootComponentGroup-RootComponentName />:

//Setup Components
<my_scenario-setup-action />
<my_scenario-setup-display />

//Feature Components
<my_scenario-feature-action />
<my_scenario-feature-display />

Those represents entry points for a Scenario, making it fast & easy to Integrate ⚡️

Setup Root Components

The Setup Root Components securely handle the API provider authentication credentials (OAuth Client ID / Secret, API Key, Basic Auth).

Depending on the Scenario integration context, you might:

  • Use your own API Credentials
  • Ask users (or admin) to provide their API Credentials

By providing Setup Root Components, Scenarios are adaptable to any context!

Intents

Intents represent the backend of a Scenario, in charge of querying an API and preparing/transforming fetched data. This is very close to the concept of a BFF.

Every intent is a Javascript function that can be called from components. Components are able to call Intents using the @Intent() decorator (more here).

Bearer provide an Intent generator command to help create Intent.

Components (Views)

Components are in charge of displaying data fetched from Intents to users.

Every Scenario provides a "feature" group with two RootComponents, "action" and "display", named feature-action.tsx and feature-display.tsx. Root Components can nest and stack many custom Components located into the views/components/ directory.

Bearer provide a Component generator command to help create component.

Components

Lean more about building & using Components in Bearer

Navigator

Root Components can be thought as tiny encapsulated micro application.

They can stack many (sub)components to provide a rich experience. Navigation between them is handled by the <bearer-navigator/> component.

Between Root Components, Navigator, Components & Intents here is how everything is linked:

By default BearerNavigator is rendered as a popover, but can easily be customized.

Below an example:

import { Component } from '@bearer/core'
import '@bearer/ui'

@RootComponent({
  role: 'action',
  group: 'feature'
  styleUrl: 'feature.css',
  shadow: true
})

export class helloWorldAction {
  render() {
    return (
      <bearer-navigator direction="right">
        <span slot="navigator-btn-content">Feature Action</span>
    	  <bearer-navigator-auth-screen />
      </bearer-navigator>
    )
  }
}

Navigator Usage

Lean more about the usage of the Navigator