Namespaces

The main concept you need to know in order to develop a plugin and a plugin-friendly application

What is this

Namespace marks a place that is available for the plugin system, and hence can be modified by plugins. In Mosaic-friendly application, it is advised to have as many namespaces as possible.

This directive accepts a string value, as shown below (as opposed to directives which accept object parts).

class

/** @namespace Some/Namespace/Here */
class A {
    ...
}

function

/** @namespace Some/Namespace/Here */
function some() {
    ...
}

arrow

/** @namespace Some/Namespace/Here */
const some = () => {
    ...
}

fetch(something).then(
    /** @namespace Some/Other/Namespace */
    (data) => ...
);

export

/** @namespace Some/Namespace/Here */
export const some = () => {
    ...
}

/** @namespace Some/Other/Here */
export class Other {
    ...
}

/** @namespace Some/Other/More */
export default class OneMore {
    ...
}

Mosaic started in ScandiPWA - extensible React storefront. As you can see, each and every class and function throughout the application has a namespace and hence is absolutely plugin-friendly.

Plugins use namespaces to intercept operations with things the namespaces belong to.

How does it work

For namespace comments to work, Mosaic requires babel-plugin-mosaic-middleware-decorator plugin. It can be found here. This plugin processes the code during the build and transforms the logic as seen below.

If you don't use the Babel plugin mentioned above - the namespace comments will not work properly. Be aware of that - if you are willing to use Typescript, you will need to migrate build process to Webpack + Babel stack (or Create React App).

All of the instructions in the Getting Started guides handle this for you.

Before

/** @namespace Some/Namespace */
class SomeClass extends SomeParent {
    ...
} 

After

/** #namespace Some/Namespace */
const SomeClass = Mosaic.middleware(
    class SomeClass extends Mosaic.Extensible(SomeParent) {
        ...
    },
    'Some/Namespace'
);

Hence, it is possible to use Mosaic without Babel, but strongly not recommended.

Any package containing@namespace magic comments must have a mosaic block declared in its package.json file. Otherwise,@namespace magic comments will not be handled correctly during the build time, hence will not work.