bp-app-template

A template for billing & payments applications

Table Of Content

• Motivation
• Steps
  • Getting Started
  • Initial Example
  • Props
  • Routes
  • Contexts
  • GraphQL And REST Clients
    • GraphQL
    • REST
  • Config And environment Variables
  • Creating A New App
  • Migrating An Existing App
• Development
• Deployment

Motivation

Having an Account Manager that is a React App, it was decided to write the guest apps as NPM modules which will be imported by the hosting app. This repo contains the bp app template with which all other guest apps will be created.

Steps

Getting Started

• Create your new app, following the bp-[APP_NAME] convention.
• Pull the latest version of bp-app-template, using the following command:

git pull [email protected]:WeConnect/bp-app-template.git master

• Head over to package.json and change the name of your project to the name of your app:

{
...
    "name": [APP_NAME],
...
}

• Head over to the production webpack config and change output.library to the name of your app:

...
  output: {
    ...
    library: [APP_NAME],
    ...
  }
...

Initial Example

The initial template has an example component named example and a corresponding story file. You can view these to get a feel of how the components should behave, then delete the example folder once you're ready to start.

Pay attention that this component is used in the routes.js file, more on this later.

Props

Your App.js component receives a baseUrl prop from the host app. Use it to initialize your routes.

Routes

Under routes.js you can view the initial default routes, which correspond to the example component. Each route object in the exported routes array is mapped in App.js to a <Route> component. You can read here about the props <Route> receives.

After reviewing the different routes, adjust them according to your app.

🚨 IMPORTANT 🚨 - your App.js component receives a baseUrl prop from the host app. Use it to initialize your routes.

Contexts

Contexts provide a way to pass data through the component tree without having to pass props down manually at every level. Apps created by this template take under consideration that the host app already wraps this app with different context providers (e.g. - locations provider which is responsible to pass props of the current location).

To handle the possibility that a context isn't defined, the host app exposes a getContext function that receives the name of the context and returns the context object which includes the context itself, its provider and consumer.

Import:

import getContext from "contexts";

Usage:

const { context, Provider, Consumer } = getContext("locations");

Use the provided contexts to get information about the current location, auth info, etc.

GraphQL and REST clients

No need to init a GraphQL client by yourself or have a REST client config anymore. The imports are from clients/graphQL or clients/rest.

GraphQL

The GraphQL client is initiated out-of-the-box by the host app. All you have to do is call the query function that is exported. The function receives two arguments:

• The query string representation.
• The variables that are used by the query string.

The function returns a promise with the query result/error.

Import:

import { query } from 'clients/graphQL';

Usage:

const queryString = `
  query ($userId: number!) {
    user($userId: $userId) {
      name,
      birthday
    }
  }
`;
query(
  queryString,
  { userId: 1 }
).then(result => {
  // Do something with result
}).catch(error => {
  // Do something with error
});

REST

The REST client receives an config object with the following attributes:

• url - the server URL that will be used for the request
• method - the request method to be used when making the request
• body - the data to be sent as the request body
• headers - the headers that the server responded with. All header names are lower cased
• params - the URL parameters to be sent with the request. Must be a plain object
• responseType indicates the type of data that the server will respond with. options are: 'arraybuffer', 'document', 'json', 'text', 'stream' (browser only: 'blob')

The function returns a promise with the result/error.

Import:

import restClient from 'clients/rest';

Usage:

restClient(
  {
    method: 'get',
    url: "www.wework.com",
    params: {
      userId: 1
    },
    responseType: 'blob',
  }
).then(result => {
  // Do something with result
}).catch(error => {
  // Do something with error
});

Config and environment variables

As this app is going to be hosted in another app, all environment variables and config will be defined by the host app. To get a variable you need to import the config object and call the config.get function with the name of the variable.

Import:

import config from "config";

Usage:

const API_URL = config.get("API_URL");

If the variable isn't defined by the host app, the function will return undefined.

Creating A New App

• When creating a new app, simply create components under the components folder. Make sure that App.js imports these components.
• You should have all your js source code under the src folder.

Migrating An Existing App

• When migrating an existing app, simply transfer all components to the components folder. Make sure that App.js imports these components.

• You should have all your js source code under the src folder.

• Install all the dependencies from your existing app.

• If necessary, add an .npmrc file with wework's NPM_TOKEN.

• Change all imports of GraphQL and REST clients according to the GraphQL and REST clients.

  Remove the GraphQL init function call if you used it.

• If you're passing props like accountUuid or locationUuid from component to component, start using the contexts that the host app exposes. Read about it under contexts.

• If your app uses portalFunctions, remove all usages, as now the layout will be determined according to the route. Currently these are functions such as requestFullScreen which are a leftover of our past architecture.

Development

To start the development server, run yarn start.

The entire development server config resides in the dev-server folder.

The dev-server's main job is to simulate running the app inside a host app, which is the root.js file. This means it contains everything the host app contains, including:

• A wrapping <Router> component
• GraphQL and REST clients. The GraphQL client is initialized in root.js.
• All relevant context providers, which means you can consume all context info.
• Config and environment variables, exposed through the config.get() function. In order for you to develop locally, make sure you have a local .env with the environment variables you need, and make sure that config.js exposes these variables. The .env file will not be added to your git commit, as the actual variables will be provided by the host app.

Deployment

These apps are NPM modules by behavior, but in order for us to always work with the latest version and so we could always have the same version (instead of bumping the version multiple times), we will install the apps using their Git urls.

You can read about it here.

When installing a guest app in your host app, simply run the following command (the example is using yarn):

yarn add git+ssh://[email protected]/WeConnect/[APP_NAME].git#[BRANCH]

The app will be added as a dependency, using its name as appears in its package.json.

To install the latest version, simply uninstall & install it again.