@mashroom/mashroom

Mashroom Server

Mashroom Server is a Node.js based Microfrontend Integration Platform.

This package contains the core of Mashroom Server. It contains core services for managing plugins and default plugin loaders for Express middleware, Express webapps and shared code as services. It also provides a common logging infrastructure.

From a technical point of view this is s a plugin loader that scans npm packages (package.json) for plugin definitions and loads them at runtime. Such a plugin could be an Express webapp or a SPA or more generally all kind of code it knows how to load, which is determined by the available plugin loaders. Plugin loaders itself are also just plugins, so it is possible to extend the list of known plugin types.

Usage

The easiest way to start is to clone one of the quickstart repositories:

• mashroom-quickstart
• mashroom-portal-quickstart

You can find a full documentation with a setup and configuration guide here: https://www.mashroom-server.com/documentation

Changelog

2.3.0 (February 10, 2023)

• Portal: Made sure that the session is not touched for resource requests (images, JS, CSS) and the set-cookie header not set. Otherwise, the resources will not be cached by proxy servers.
• Kubernetes Remote App Registry: If the service port changes the App definition gets reloaded with the next scan
• Portal: Hot reload of Apps works now on all sites and when mashroom-vhost-path-mapper is being used
• Kubernetes Remote App Registry: Added a config property unregisterAppsAfterScanErrors to control if Apps should be unregistered if a service cannot be reached anymore
• Remote App Registry: Added a config property unregisterAppsAfterScanErrors to if Apps should be unregistered if an endpoint cannot be reached anymore. This fixes the problem that Apps got unregistered if the endpoint was down during the refresh. Default is -1 which means Apps are never unregistered automatically. A value of 3 would mean that Apps would be unregistered after 3 retries or 3 minutes if the scan interval is 1 minute.
• Remote App Registry: Unregister Apps properly if they disappear from an endpoint with multiple Apps
• Admin Toolbar: If a page gets deleted all subpages are moved up the parent level (until now they just disappeared)
• Admin Toolbar: Doesn't allow to remove the last Site anymore
• Portal: Made sure that all related resources are removed from the storage if a Site or Page is deleted (Permissions, App Instances, ...)
• Portal: Added a method checkLoadedPortalAppsUpdated() to the portalAppService which allows it to check if the Portal Apps loaded in the Browser have been redeployed. This could be used in a (long-running) dynamic cockpit to inform the user that some Apps might not work as expected anymore and a reload of the page would be recommended.
• Sandbox Apps: Shows now the number of loaded resources, the resources size and (if available) the memory usage of the page
• Portal: The App Info shows now also the number of the loaded resources for an App and the decoded size of those resources
• Core: Uses nx for building in dev mode if it is available. This should lead to a much faster startup in dev mode, especially if the distributed cloud cache is used.
• Core: Improved support for ts-node. If Mashroom runs with ts-node all config files can be written in TypeScript. This includes plugin config files. Example server config file mashroom.ts:

  import type {MashroomServerConfig} from '@mashroom/mashroom-json-schemas/type-definitions';
  const serverConfig: MashroomServerConfig = {
      name: 'Mashroom Test Server 7',
      port: 5050,
      // ...
  ];
  export default serverConfig;

• Portal: Disabled caching of Portal App chunks (from code splitting) that do not include a content hash in the file name. Because in that case the Browser would cache the chunk forever even if the content changes. If you use webpack you can add the content hash like this to chunk names:

   output: {
       // ...
       chunkFilename: 'my-app.[contenthash].js',
   }
  

• Portal: Added support for ES6 modules in Apps. It will automatically be turned on if the bootstrap file name ends with .mjs. Checkout the example here: https://github.com/nonblocking/mashroom-plugin-demos/tree/master/packages/mashroom-demo-plain-es6-portal-app That is just a neat tech demo, in the real world you should always use a bundler, because loading dozens of uncompressed small files is very inefficient, and it is also not possible to load libraries from node_modules.
• Portal: Added support for code-splitting in shared libraries. The only precondition is that the name of the chunks needs to be <shared_lib_base_name>.<chunk_name>.js; you would configure that in webpack like this:

    output: {
      path: __dirname + '/dist',
      filename: 'my_shared_library.js',
      chunkFilename: 'my_shared_library.[contenthash].js'
    }
  

• Core: Fixed the type of pluginContext.service.<service_ns>: it can now be undefined because the plugin might not be loaded. This can be a BREAKING CHANGE, and you have to following options to fix TypeScript errors:

   // If the services is added as "required" in the plugin definition
   const requiredService: MashroomSecurityService = pluginContext.services.security!.service;
   // Otherwise
   const optionalService: MashroomSecurityService | unknown = pluginContext.services.security?.service;
  
   // Alternatively extend MashroomServicePluginNamespaces in a type declaration file
   declare module '@mashroom/mashroom/type-definitions' {
       export interface MashroomServicePluginNamespaces {
           security: { service: MashroomSecurityService; } | /* might not be loaded yet */ undefined;
           // Orther service plugins
       }
   }