Route serialization to support Shopper SEO URL mapping integration

[hajinsuha1]

Description

Implemented dynamic routes by introducing a RoutesContext/RoutesProvider to the Switch component.
Additionally implemented serialization of routes from server to client when getRoutesAsync is implemented.

Types of Changes

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Documentation update
• Breaking change (could cause existing functionality to not work as expected)
• Other changes (non-breaking changes that does not fit any of the above)

Breaking changes include:

• Removing a public function or component or prop
• Adding a required argument to a function
• Changing the data type of a function parameter or return value
• Adding a new peer dependency to package.json

Changes

• update Switch component to load routes from RoutesProvider and RoutesContext
• Server: update react-rendering.js to serialize extensions that have getRoutesAsync implemented and save it under window.__EXTENSIONS__ global variable
• update ApplicationExtension to:
  • cache results from getRoutesAsync to _cachedRoutes property
  • deserialize routes from window.__EXTENSIONS__ when on the client and save it under _cachedRoutes

How to Test-Drive This PR

• First of all, temporarily bring back the changes to extension-url-mapping, typescript-minimal, and debug logs by reverting the commit 26a60d6

  git revert 26a60d644671b387736d3554d9a8a6af29d1b888
  

• npm ci at the monorepo root
• Then cd to the typescript-minimal directory and run npm start (OR npm run start:inspect to see the server logs more easily)
• cd into the template-typescript-minimal and start the server npm start
• verify http://localhost:3000/__pwa-kit/getting-started displays the SamplePage component (this route is added via extension-url-mapping which is added for testing purposes)
• verify in the terminal logs (server-side) only the UrlMapping extension routes are serialized
• verify in the browser logs (client-side) only the UrlMapping extension routes are deserialized and added to all routes

Checklists

General

• Changes are covered by test cases
• CHANGELOG.md updated with a short description of changes (not required for documentation updates)

Accessibility Compliance

You must check off all items in one of the follow two lists:

• There are no changes to UI

or...

• Changes were tested with a Screen Reader (iOS VoiceOver or Android Talkback) and had no issues
• Changes comply with WCAG 2.0 guidelines levels A and AA
• Changes to common UI patterns and interactions comply with WAI-ARIA best practices

Localization

• Changes include a UI text update in the Retail React App (which requires translation)

[hajinsuha1]

because extendRoutes modifies the original routes array, here I prefix the component displayName only when it doesn't have a prefix already. So any new routes added via an applicationExtension extendRoutes call will get the extension prefix added

[hajinsuha1]

initialize the component map with the universal components added to routes in pwa-kit-react-sdk

[hajinsuha1]

I was finding when I had this logic in ApplicationExtension.getComponentMap() it would error that it can't find ./pages.

Will continue to look for a solution that makes it so this function doesn't need to be implemented by every extension. Looking at making a protected method getComponentMapByPath that does the importing and have the default implementation call that method with the ./pages path to workaround this

[hajinsuha1]

• consider only serializing one route from extendRoutes
• move serialization logic to extension instead of base react-sdk
• force customers to create a new extension to use an async extendRoutes that includes warnings to make sure the customer uses fast functions in the impl. This will prevent customers from creating slow functions with bad practices

[hajinsuha1]

extension classes will need to implement the getComponentMap function as putting this logic in ApplicationExtension.getComponentMap gives errors when attempting to import from ./pages since this folder only exists in extensions

[bendvc]

Can you remind me again why this is async?

[hajinsuha1]

Good point this does not have to be async!

[hajinsuha1]

it looks like route.props is not a field of RouteProps however the serialization/deserialzation seems to still work!

[hajinsuha1]

Currently I pass in the componentMap, I'll look to refactor this code to call the this.getComponentMap directly

[hajinsuha1]

@bendvc where in the code can I add a field to config.app?

[bendvc]

I don't think we'll be serializing this under the CONFIG. We might come up with an alternative.

[bendvc]

This method being async is also suspicious. The flow that I was anticipating was to have the ssr flow load the routes and those routes get "cached" in a private variable that the serializer can use.

[bendvc]

I'm not a huge fan of this conditional logic here. We should investigate how we can have a single called to each getRoutes.

We might be able to accomplish this by moving some of the deserialization logic either into the constructor of the extension, or somewhere else like that handlebar template so during the instantiation process we also deserialize. I'm not sure which one is the best just yet.

[bendvc]

Would there be any downside to just returning an empty array if the getRoutesAsync is not defined? Or are we using that null value somewhere as an indicator that getRoutesAsync isn't defined?

A possible alternative is to throw if you try to serialize and getRoutesAsync is not defined or has not ran?

[hajinsuha1]

Updated it to return an empty array. The effect is that during serialization in react-rendering we filter out serialized routes that are an empty array before saving it to the global window variable

[bendvc]

Maybe you touch on this a little bit here with regards to my above comments. I'm still wondering if we need to have 3 states, throw, null and valid value. Seems like it might be more difficult to understand.

[hajinsuha1]

I've returned an empty array whenever possible however I feel we still need to have the null case for the initial cachedRoutes value.

The reason is the cacheMethodResults only caches the value when the property is null or undefined. And since this is a general function I don't think caching when the property is an empty array would be a good idea. But open to suggestions.

Here are the changes: 3d5febc

[hajinsuha1]

use private variable for cachedRoutesInvoked!

[bendvc]

Is name guaranteed to be unique?

[hajinsuha1]

There is nothing stopping 2 extensions having the same name. e.g., 2 extensions can have the same class name defined in setup-app.js.

I guess we could either

1. throw an error stating that 2 extensions cannot have the same name
2. use a unique name like the package name in package.json

const path = require('path')
const fs = require('fs')

function getPackageNameFromInstance(instance) {
    const filename = getClassFilePath(instance)
    if (!filename) return null

    let dir = path.dirname(filename)
    while (dir !== path.dirname(dir)) {
        const pkgPath = path.join(dir, 'package.json')
        if (fs.existsSync(pkgPath)) {
            return JSON.parse(fs.readFileSync(pkgPath, 'utf8')).name
        }
        dir = path.dirname(dir)
    }

    return null
}

function getClassFilePath(instance) {
    const constructor = instance.constructor
    for (const mod of Object.values(require.cache)) {
        if (
            mod.exports === constructor ||
            mod.exports?.default === constructor ||
            Object.values(mod.exports).includes(constructor)
        ) {
            return mod.filename
        }
    }
    return null
}

[hajinsuha1]

Put note above TODO to use getId() ticket

[bendvc]

Instead of filtering after running the serialize, why now only serialize the extensions that should be serialized? ... in the jsdoc comment above you say "some" .. maybe that is a good indicator to use the some() function on the application extensions array.

[bendvc]

Is you want to get super specific about this type you might want to do something like this:

type ComponentMap = {
  [key in ReturnType<ApplicationExtension['getName']>]: React.ComponentType<any>
};