@nxtdtc/nxt-warehouse v2.1.0

:factory:

Warehouse

How to Use

Local Development

Best Practices and Testing

Publishing

A redux-based library to handle common front end interactions with global state and consolidate how our front ends communicate and receive data from our microservices.

The approach in this library generally follows the advice of Martin Fowler

If you are using redux, the usual approach is to have a single, global, shared store for the entire application

and redux

Try reducer composition first, and only use multiple stores if it doesn't solve your problem.

Reducers are exposed as exports and can be composed in the front end using combineReducers while also allowing the consumer to use its own reducers for app-specific logic.

Example:

import {
  AccountReducer,
  CatalogReducer,
  StompReducer,
  CartReducer,
  OrderReducer,
  StaticPageReducer,
  StorefrontReducer,
  PaypalReducer,
  NotificationReducer
} from '@nxtdtc/nxt-warehouse/lib/WarehouseReducers';

import AppSpecificReducer from './AppSpecificReducer';

const rootReducer = combineReducers({
  stomp: StompReducer,
  storefront: StorefrontReducer,
  cart: CartReducer,
  account: AccountReducer,
  order: OrderReducer,
  catalog: CatalogReducer,
  utils: NotificationReducer,
  page: StaticPageReducer,
  paypal: PaypalReducer,
  localReducer: AppSpecificReducer
});

How to Use

In the consuming front end, we create a Warehouse object which stores references to the store, apiClient, and replyTo.

const apiClient = Stomp.over(wss);
const replyTo = ObjectId();

export const sharedStore = new Warehouse(apiClient, replyTo, store);

We handle ALL incoming websocket responses like so:

const onStompConnectSuccess = async () => {
  console.log('Successfully Connected');
  store.dispatch(connectStomp({ apiClient, replyTo }));

  apiClient.subscribe(
    `/queue/${replyTo}`,
    (body) => {
      sharedStore.handleResponseFromStomp(body);
    },
    {
      'auto-delete': true
    }
  );

  ReactDOM.render(<Main />, document.querySelector('#root'));
};

Any common actions that are shared across apps including cart, account, bootstrap, storefront, staticpage, catalog and paypal actions are stored in this library.

To use a common redux action in a component:

import {
  requestSubscribeEmail,
  requestCheckEmailExistence
} from '@nxtdtc/nxt-warehouse/lib/AccountActions';

You can use all redux hooks as well as mapStateToProps as you normally would and any store updates will be reflected in your redux store.

Local Development

In the warehouse directory:

• npm install
• npm link
• npm start this will start webpack with live reloading enabled

In the consuming front end directory:

• npm link @nxtdtc/nxt-warehouse

If you run into issues where you are asked for sudo permissions you may need to make sure you are using a compatible version of node. Node Version Manager is useful tool for doing exactly what it sounds like.

Best Practices and Testing

This library is leaning towards ducks architecture without fully doing so :confused:

In an effor to simplify our redux architecture, types and reducers are stored in the same .ducks file. The naming conventions here are important as our webpack configuration has some logic to look for files ending in .actions or .ducks

Any functions which only serve to handle responses from our apiClient should follow the naming convention <"Name">Handler.js and be exposed in our Warehouse class.

There is a LOT of untested code here. If you touch a file, you should increase the test coverage there until we reach a sufficient level of coverage.

To run tests: npm test

Publishing

For the most part, we should be publishing minor versions of our library. The logic behind this is that if we need to publish a hotfix but have unwanted changes from another developer who is working on v1.1.0, we find ourselves in a position where we have to pick apart a branch to get the changes we need.

By publishing minor versions, we can more easily do hotfixes.

Scenario:

An issue is discovered on v1.0.0 which is currently in production but we have published v1.2.0 which has changes we don't want or need

To begin a hotfix:

• checkout library at the version currently in production git checkout tags/1.0.0 or use the commit hash
• create a branch off what is in prod git checkout -b DC-1234_hotfix
• when your work has been approved cut a new patch version npm version patch
• update the front end with the correct version and deploy

To cut a new version

• checkout master git checkout master
• create a branch to do your work
• once your branch has been approved merge to master
• create git tags and bump the version npm version minor
• publish your changes npm publish
• update any front ends which depend on your new changes

Major version npm version major should be reserved for breaking changes and should include a discussion with the reviewer to determine if your change is breaking or not. Most changes should fall into minor.

Misc

Useful commands:

• npm run analyze - creates a visualization of our bundled assets and can be used to determine any dependencies which are hogging up space
• npm run coverage - run the test suite and get a print out of coverage by functions, lines, branches, etc per file

Improvements

There's always room for improvement :bowtie: as this codebase was mostly ported from one of our beginning projects. Side effects should be moved to used redux-sagas or some other async library instead of being called in our actions. Dispatches with no payloads should be examined and our test coverage should reach the limits of testability.