@demium/react_library

React components + utils library for Demium's web (+ mobile in the future) projects to rely on. It offers tested functionality + styling out of the box, making front development fast and seamless.

Current demo site

Deps

• Library core built over create_react_library v2.6.7
• Components built with React (+ Hooks)
• Styles (SASS + CSS) are a customization of Bootstrap
• Tests: Jest + react_testing_library + Jest-Dom
• Demo site built over create_react_app.
• Transpiled with Babel
• Resources bundled with Rollup

How it works

There are 2 package.json files:

/src -> Main code base

All exportable content. It's currently organised as follows:

• /assets: Icons, images (logo + favicon) and any static asset. Will probably disappear once we set up a proper CDN service.
• /components: React components, all functional (+ Hooks).
• /models: Javascript objects to set contracts between services. Currently exporting objects for API request errors, API request success, etc.
• /services: Javascript functions in charge of a certain functionality. Currently exporting a "FakeApiService" for all our sites to build a Fake API Data layer on all web implementations.
• /styles: Bunch of SASS files to override default variables for Bootstrap (see Styles structure below for a detailed description).
• index.js: Library main file. Everything we want to export as a consumable of @demium/react_library, must be both imported and exported here. Compilation process will grab this file (and this file only!) to build the /dist folder.

Naming convention

In order to quickly tell apart exported functionality from internal files, everything that ends up exported starts its name (and file name) with "DEM" (EX: DEMHeader, DEMFakeApiService, etc.).

Styles structure

We have built our styles over Bootstrap's SASS, which is quite customizable.

• We broke apart the huge list of SASS variables into component related files (see /src/styles/variables/bootstrap).
• Whenever we want to override one of Bootstrap's default values, we create a Demium variable (its name must ALWAYS start with $dem-), we place it in the Demium variables folder (/src/styles/variables/demium), and we consume it where the override must take place. This way we grant full control of custom changes to a single file, which is highly maintainable, and also enables the possibility of theming our webs just in seconds.
• In case Bootstrap does not fulfill what we want to achieve, we write custom SASS (/src/styles/custom). The process of creating variables is exactly the same as in the previous step, ALWAYS granting control to Demium variables.

/demo -> Demo site

Simple create_react_app web application, currently published on our Bitbucket workspace

Local dependency of @demium/react_library

It's important to note how Demo site is consuming @demium/react_library.

We want Demo site to represent a real use case, so it needs to rely on @demium/react_library as if @demium/react_library's code base didn't coexist with Demo site's.

Thus, Demo site's package.json declares a local dependency to @demium/react_library:

"dependencies": {
    "@demium/react_library": "file:../",
    ....
}

This declaration let's npm know where to navigate in order to find the package.json of the Node project you want to depend on. In our case, "file:../" is telling npm to navigate back one path, where the library main package.json is located.

Consuming the library

Currently Demo site works just as a visual example. In the following versions will also represent the documentation of the library, ending up becoming a proper Design Patterns site.

As of now, we need to look at Demo site's code to get good example of each component :| .

Developing

Testing

As mentioned above, we are using Jest + react_testing_library + Jest-Dom for our test suite.

As of 06/08/2019, the code coverage of the library is 82.8%. The percentage is actually a bit inaccurate, as the coverage tool is also considering the Demo site code base, which works as an example and will have no tests. The actual percentage of exported code (which is the important part) is even higher.

We are gradually grouping our tests on 3 different sections:

• Functionality tests. The component works as expected: triggers expected handler when clicked, etc.
• Styling tests (only when UX/Design layer has been implemented). Expected HTML structure + CSS classes for the sake of respecting Styles.
• Export tests (only if tested component is expected to be exported by the library, i.e. its name starts with DEM). Simple render tests but importing the module from index.js instead of its code base location.

Launching dev environment

npm start on /src

First of all, we need to npm install.

For npm install to work, we first need to npm install the Demo site (cd /demo). @demium/react_library declares devDependencies that are purposely declared as peerDependencies. The reason of this weird double declaration is related to version issues that are out of the scope of this docs.

"peerDependencies": {
    "axios": "^0.18.0",
    "react": "^16.8.6",
    ....
},
"devDependencies": {
    "axios": "file:./demo/node_modules/axios",
    "react": "file:./demo/node_modules/react",
    ....
}

Once done, npm start will trigger Rollup compilation process, in watch mode, that will compile everything imported & exported from src/index.js.

npm start on /demo

First of all, we need to npm install. No extra dependencies here, just wait for it to finish.

npm start will to trigger just a create_react_app start standard process, hosting the site on localhost:3000 by default.

npm run sass on /src

If you are not going to develop SASS code, you don't need this script running. You can even develop SASS code without it running too, but you will end up wanting to run it, and this is why:

Rollup is not good watching changes on SASS imports: if you make changes on main.scss, Rollup will compile it for you. However, if you change a partial (EX: _custom.scss) imported in main.scss, Rollup won't see it and you need to manually save on main.scss for Rollup to compile your changes.

This situation made us create a dedicated script that just runs the standard SASS compilator for Node, node-sass, in watch mode, and outputs its result in /dist. It does the same thing npm start on /src does, it just enables the watch mode.

npm start on /src && npm start on /demo

Here is where the magic happens! Just npm starting both Node modules will make everything connect:

• Any change on /src will be compiled by Rollup.
• Resulting compilation process outputs in the /dist folder.
• As Demo depends locally on @demium/react_library, it relies on its package.json's main, which happens to be "main": "dist/index.js".
• Thus, as the content of /dist is just another node_modules for Demo site, its npm start is watching changes on its content too!
• Demo site reloads.

npm start on /src && npm start on /demo && npm run sass on /src

Even more magic! See previous section to understand the flow.

Adding npm run sass just makes the whole flow to compile also when ANY SASS file changes.

Additionally, if the compilation changes just affected the resulting index.css and index.js didn't change, Demo will hot reload the styles for you, no web refresh at all!

npm start on /demo && npm run sass on /src

Same as above, just bear in mind Rollup is not running, so no changes in JS will be compiled whatsoever