The common utility module for @mtfh/root
.
The Utility Module is a single-spa
module that is globally exposed at runtime, from
which other microfrontends can import
any exposed values. So with this in mind it is not
possible to have one microfrontend use a specific version of @mtfh/common
, so we need to
be quite careful around what is a candidate for inclusion in this module. Breaking changes
introduced will need to be resolved in all microfrontends that consume it.
We explictily do not expose any endpoints, or business logic (with authentication as the exception) into this module to avoid problematic releases.
This is the checklist for a candidate:
- Your feature is used in more than 1 (preferably 2) microfrontends.
- Your feature requires little to no maintenance.
- Your feature includes no business logic, including any concept of Data Entities.
- Your feature introduces agreed best practices and contributes to the overall standards.
Change requests will require an impact assessment to determine viability. All exports of this module are optional and should not block a team in their contributions to the project.
Part of the process of making changes to this repository involves ensuring that the
pipeline mtfh-tl-e2e-tests
will pass in Circle CI, even if you do not modify or add
tests (which you should).
Failure to do this will result in:
- Less test coverage for MMH, adding tech debt, and all other disadvantages that come with untested code;
- The mtfh-tl-e2e-tests pipeline may end up being BLOCKED by any changes made to MMH, which could affect other developers and ALL future releases on ALL micro-frontends;
Link to the Circle CI mtfh-tl-e2e-tests
pipeline:
https://app.circleci.com/pipelines/github/LBHackney-IT/mtfh-tl-e2e-tests
Authentication is currently implemented through Google OAuth.
On import of the library a RxJs SharedBehaviour
instance is created of the decoded JWT
auth cookie. Making available the AuthUser
.
Your app can import this $auth
instance and extract the current value.
import { $auth, AuthUser } from "@mtfh/common/lib/auth";
const user: AuthUser = $auth.getValue();
You are able to subscribe to changes to the AuthUser
, useful for UI state changes.
const subscription = $auth.subscribe((authUser) => {
console.log(authUser);
});
subscription.unsubscribe();
A custom instance of axios
is exposed that is preconfigured with an interceptor to add
an Authorization
header, based off the authenticated user.
import { axiosInstance } from "@mtfh/common/lib/http";
axiosInstance.get("/url");
In addition it also provides the mechanism to cancel an axios request, without the need to
import axios
as a dependency into your project.
import { axiosInstance, createCancelToken } from "@mtfh/common";
const cancelTokenSource = createCancelToken();
axiosInstance.get("/url", { cancelToken: cancelTokenSource.token });
cancelTokenSource.cancel();
Services and models to use APIs live on this microfrontend, under the /api folder, following this folder convention:
- service-name
- version (as 'v1', 'v2', etc...)
- service
- types
- version (as 'v1', 'v2', etc...)
They can be used on other microfrontends with imports like
import { Person, usePerson } from '@mtfh/common/lib/api/person/v1'
To add a new service,
add a path to webpack with its corresponding env nar (if needed) If you add a new env var,
mind that it will need creation as well on the circle ci config of this repo and on AWS
param store (for each environment)
The recommended tool is yalc. The only caveat is that it can't handle 2 level dependencies, for instance using tenure, which imports personal-details and this last one uses common
MFE dependency versions are handled via hash on yarn.lock, to update a dependency, just
yarn add https://microfrontend-url.git
The provided components are React components of lbh-frontend.
import { Input } from "@mtfh/common/lib/components";
The following hooks are available:
- useAxiosSWR
- useAxiosSWRInfinite
- useBreakpoint
- useFeatureToggle
- useConfiguration
- useErrorCodes
import { useFeatureToggle } from "@mtfh/common/lib/hooks";
Currently we use a trunk based approach to development and CD is possible because of the use of feature toggles. For more information around how to create and use feature toggles, read this doc
The common library has manual code splitting in place, defined as entry points within
webpack. These files get automatically marked as externals, so its important to import
from the @mtfh/common/lib/*
alias when cross importing. These are consolidated into the
import-map.json
, so made available at runtime.
When this library is installed in a micro-frontend its sole purpose is to satisfy tests as well as provide typings.
NB: Typescript does not support package.json
exports
yet, so we have to maintain the
dist output to match the source. ie the usage of lib
.
Currently, common holds access to most APIs, so it's required to define their URLs via ENV vars. Like:
CONFIGURATION_API_URL_V1=https://api-url.com/api/v1
CONTACT_DETAILS_API_URL_V1=https://api-url.com/api/v1
CONTACT_DETAILS_API_URL_V2=https://api-url.com/api/v2
REFERENCE_DATA_API_URL_V1=https://api-url.com/api/v1
TENURE_API_URL_V1=https://api-url.com/api/v1
NOTES_API_URL_V1=https://api-url.com/api/v1
NOTES_API_URL_V2=https://api-url.com/api/v2
PERSON_API_URL_V1=https://api-url.com/api/v1
PERSON_API_URL_V2=https://api-url.com/api/v2
PROPERTY_API_URL_V1=https://api-url.com/api/v1
LOGGING_API_URL_V1=https://api-url.com/api/v1
ADDRESS_API_URL_V1=https://api-url.com/api/v1
ADDRESS_API_URL_V2=https://api-url.com/api/v2
EQUALITY_INFORMATION_API_URL_V1=https://api-url.com/api/v1
Urls are available on the API gateways of AWS