Migrating feature-u to V1

Beginning with feature-u V1 Cross Feature Communication has been completely re-designed to include UI Composition as a core offering of feature-u (thanks @jeffbski for the design collaboration)!

• This refactor promotes one solution for all Cross Feature Communication (i.e. Actions, Selectors, UI Components, API, etc.), making it comprehensive and universal.

• This is an extremely powerful enhancement, and even extends to things like Feature Based Routes.

• It represents a significant step forward in providing seamless feature-based development!

This guide will walk you through the details of migrating to feature-u V1 from an older release.

At a Glance

• What Has Changed
• Why such an abrupt change?
• feature-u migration
• feature-redux migration
• feature-redux-logic migration
• feature-router migration

What Has Changed

At a high level, the following items have been impacted (more detail can be found at Cross Feature Communication):

• In an effort to standardize terminology (and remove ambiguity), the term fassets (feature assets) is being used throughout, replacing publicFace (on the aspect definition side) and app (on the usage side).

• The Feature.fassets aspect replaces Feature.publicFace, providing a more formal set of directives, supporting things like contractual arrangements (of usage and definition), and validation of resources.

• The Fassets object replaces the app object, to programmatically access cross-feature resources.

• The managedExpansion() function has been renamed to expandWithFassets().

• The new withFassets() higher-order component (HOC) auto-wires named feature assets as component properties.

Why such an abrupt change?

You may be wondering why V1 introduced such an abrupt breaking change, with no deprecation.

The internal magnitude of this change was fairly significant. Obviously we could have published intermediate versions with deprecation notices, while difficult (due to the nature of this change) not impossible.

Ultimately, we decided to take advantage of the pre-production status (0.1.3), and the relatively small distribution, and go cold turkey with the change.

We take your usage of feature-u seriously, along with the impact of this change.

We are excited about the V1 release. It represents a significant step forward in providing seamless feature-based development.

SideBar: To give you some background, the V1 design progressed from a simple plugin to a full core offering:

• Initially, the focus was on a new navigation plugin that supported react-router.

• With react-router's V4 release, we realized our plugin could broaden it's scope to overall UI Composition - because that is how RR V4 works.

• As a further progression, we realized that UI Composition was simply one part of the overall Cross Feature Communication. By incorporating this into a core feature-u offering, all cross-communication could use the same mechanism.

  In addition, this seemed like a good time to to standardize some ambiguous terms from our initial cross-communication attempt.

feature-u migration

1. The return of launchApp() is now the Fassets object. Per the recomendation to export this, please note that this is no longer the app object, rather the Fassets object.

2. Any feature-u API that was passing the app object as a parameter, is NOW the Fassets object.

   Depending on your IDE and dev environment, this can be a tedious proces to retrofit. If you are using some type of search, the "app" nominclature is going to appear in many different contexts.

   • Either work through your code base, one by one (searching for app parameters/variables)

   • Or focus on the various APIs summarized in the Core API (focusing on the signatures with fassets parameters).

     If you are retrofitting an Aspect plugin, do the same thing with the Extension API.

3. Any Feature.publicFace aspect must be converted to the new Feature.fassets aspect.

   While it is possible to translate a one-to-one mapping (between the old publicFace and the new fassets aspect) you are encourged to employ the new enhancments of Cross Feature Communication, such as:

   • Full UI Composition via the withFassets() HoC.

   • Resource Contracts, via the fassets.use and fassets.defineUse directives.

   • Depending on the circumstances, refactor out the featureName resource qualifier.

   Here is an example that translates publicFace to fassets with an equivilant mapping:

OLD publicFace

   publicFace: { // OBSOLETE in feature-u V1
     api,
     sel: {
       areFontsLoaded,
       isDeviceReady,
       getDeviceLoc,
     },
     actions: {
       ready: actions.ready,
     },
   },

NEW fassets.define equivalent

   fassets: { // NEW feature-u V1
     define: {
       [`${featureName}.api`]:                api,

       [`${featureName}.sel.areFontsLoaded`]: areFontsLoaded,
       [`${featureName}.sel.isDeviceReady`]:  isDeviceReady,
       [`${featureName}.sel.getDeviceLoc`]:   getDeviceLoc,

       [`${featureName}.actions.ready`]:      actions.ready,
     },
   },

feature-redux migration

If you are using the feature-redux plugin, you must install the latest version.

1. This plugin has eliminated singletons in favor of creators (to facilitate testing and server-side rendering).

    // in place of this:
    import {reducerAspect}   from 'feature-redux';
   
    // do this:
    import {createReducerAspect} from 'feature-redux';
    const reducerAspect = createReducerAspect();
   

feature-redux-logic migration

If you are using the feature-redux-logic plugin, you must install the latest version.

1. Because feature-redux-logic auto injects the Fassets object as a dependency in your logic modules (promoting full Cross Feature Communication, the logic modules in your application code must reflect this change by renaming this named parameter from app to fassets, and utilize the new fassets API accordingly.

2. This plugin has eliminated singletons in favor of creators (to facilitate testing and server-side rendering).

    // in place of this:
    import {logicAspect}   from 'feature-redux-logic';
   
    // do this:
    import {createLogicAspect} from 'feature-redux-logic';
    const logicAspect = createLogicAspect();
   

feature-router migration

If you are using the feature-router plugin, you must install the latest version.

1. Because feature-router auto injects the Fassets object as a dependency in your routes (promoting full Cross Feature Communication), the routes in your application code must reflect this change by renaming this named parameter from app to fassets, and utilize the new fassets API accordingly.

2. This plugin has eliminated singletons in favor of creators (to facilitate testing and server-side rendering).

    // in place of this:
    import {routeAspect}   from 'feature-router';
   
    // do this:
    import {createRouteAspect} from 'feature-router';
    const routeAspect = createRouteAspect();