Skip to content

Nicecactus/SRM

This branch is 1 commit ahead of master.

Folders and files

NameName
Last commit message
Last commit date

Latest commit

10b29f9 ยท Mar 6, 2023

History

57 Commits
May 27, 2021
Mar 6, 2023
May 28, 2021
Apr 21, 2021
Apr 21, 2021
Apr 21, 2021
Apr 21, 2021
May 24, 2021
Apr 21, 2021
Apr 21, 2021
May 28, 2021
May 18, 2021
Aug 17, 2021
Aug 17, 2021
Apr 21, 2021
Oct 4, 2021
Oct 4, 2021
Apr 22, 2021
Apr 21, 2021
May 27, 2021

Repository files navigation

SRM logo

SRM

Core library for Standalone React Module

NPM

How it works

SRM are react applications with extra perks. They can take props and mounted on a specific element. They are designed to be lazy or eagerly loaded into any other framework.

Building an SRM will produce several .js and .css files, all listed in the asset-manifest.json bundled along them.
The build folder content can then be served by a static server, keeping the folder structure and making sure all files are publicly accessible. A simple way to do so in production would be to use an AWS S3 bucket.

The build/asset-manifest.json file describes the entry points and assets to be fetched in order to use your SRM.
A direct url to this file will be required to load and run the SRM, as can be seen in @nicecactus/ng-srm-wrapper or nicecactus/react-srm-wrapper.

Example for https://your-domain.com:
+-- /
|   +-- your-project/
|       +-- asset-manifest.json
|       +-- favicon.ico
|       +-- index.html
|       +-- static/

Asset manifest URL: https://your-domain.com/your-project/asset-manifest.json

Getting started

1. Installation

yarn

yarn add @nicecactus/srm

npm

npm install --save @nicecactus/srm

2. Project setup

You will need react, react-dom and react-intl as dependencies.

3. CSS encapsulation (optionnal)

The following section allows to prevent CSS leaking between the SRM and the host by prefixing all classes and styles. Please consider skipping this step if you don't need this feature as it will increase the bundle size.

Note: we only provide steps for CRA at the moment, however it should be straight forward to adapt these instructions to any other bundling system.

1) Install extra dependencies

The following dev dependencies are required to customize the CRA build process without ejecting:

yarn

yarn add -D customize-cra prefix-css-loader react-app-rewired string-replace-loader

npm

npm install --save-dev customize-cra prefix-css-loader react-app-rewired string-replace-loader
2) 'Flip' the existing calls to react-scripts in npm scripts for start, build and test
package.json
  "scripts": {
-   "start": "react-scripts start",
+   "start": "react-app-rewired start",
-   "build": "react-scripts build",
+   "build": "react-app-rewired build",
-   "test": "react-scripts test",
+   "test": "react-app-rewired test",
    "eject": "react-scripts eject"
}

Note: Do NOT flip the call for the eject script. That gets run only once for a project, after which you are given full control over the webpack configuration making react-app-rewired no longer required. There are no configuration options to rewire for the eject script.

3) Copy the config-overrides.js from the example folder

Copy the config-overrides.js to the root directory.

+-- your-project/
|   +-- config-overrides.js
|   +-- node_modules/
|   +-- package.json
|   +-- public/
|   +-- README.md
|   +-- src/

4. SRM creation

index.tsx
/* Import the library */
import { SRM } from "@nicecactus/srm";

/* Create the SRM */
const orgName = 'myOrg';
const appName = 'myApp';

export interface Props {
  // Add Props to your SRM here
}

const render = SRM(
  `${orgName}.${appName}`,
  (props: Props) => {
    return (
      <>
        <span>Hello world ๐Ÿ†</span>
      </>
    );
  }
);

/* Declare typings */
declare global {
  export interface Window {
    [orgName]: { [appName]: { render: typeof render } };
  }
}

/* Export render function */
export default render;

5. Add i18n support (optionnal)

The last parameter loadMessages of the SRM() function can be used to return different dictionary based on the language set through the SRM props.
It expects a function of the following signature: (lang: string) => { [term: string]: string } in order to fit your custom translation setup.
For example, when using a different json file for each language:

const render = SRM(
  `${orgName}.${appName}`,
  ({ getUsername }: Props) => {
    ...
  },
  (lang: string) => require(`./translations/${lang}.json`) // require the json file from the translation folder
);

Example

An example SRM with a custom store and i18n can be found in the example folder.
Please see example/README.md for more details on how to run it.