@mashroom/mashroom
Advanced tools
Mashroom Server. Supports out of the box the following plugin types: 'web-app', 'api', 'middleware', 'static', 'services' and 'plugin-loader'.
Mashroom Server is a Node.js based Integration Platform for Microfrontends.
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.
The easiest way to start is to clone one of the quickstart repositories:
You can find a full documentation with a setup and configuration guide here: https://www.mashroom-server.com/documentation
Accessible through pluginContext.services.core.pluginService
Interface:
export interface MashroomPluginService {
/**
* The currently known plugin loaders
*/
getPluginLoaders(): Readonly<MashroomPluginLoaderMap>;
/**
* Get all currently known plugins
*/
getPlugins(): Readonly<Array<MashroomPlugin>>;
/**
* Get all currently known plugin packages
*/
getPluginPackages(): Readonly<Array<MashroomPluginPackage>>;
/**
* Register for the next loaded event of given plugin (fired AFTER the plugin has been loaded).
*/
onLoadedOnce(pluginName: string, listener: () => void): void;
/**
* Register for the next unload event of given plugin (fired BEFORE the plugin is going to be unloaded).
*/
onUnloadOnce(pluginName: string, listener: () => void): void;
}
Accessible through pluginContext.services.core.middlewareStackService
Interface:
export interface MashroomMiddlewareStackService {
/**
* Check if the stack has given plugin
*/
has(pluginName: string): boolean;
/**
* Execute the given middleware.
* Throws an exception if it doesn't exists
*/
apply(
pluginName: string,
req: Request,
res: Response,
): Promise<void>;
/**
* Get the ordered list of middleware plugin (first in the list is executed first)
*/
getStack(): Array<{pluginName: string; order: number}>;
}
Accessible through pluginContext.services.core.websocketUpgradeService
Interface:
/**
* A services to add and remove HTTP/1 upgrade listeners
*/
export interface MashroomHttpUpgradeService {
/**
* Register an upgrade handler for given path
*/
registerUpgradeHandler(handler: MashroomHttpUpgradeHandler, pathExpression: string | RegExp): void;
/**
* Unregister an upgrade handler
*/
unregisterUpgradeHandler(handler: MashroomHttpUpgradeHandler): void;
}
A plugin-loader plugin adds support for a custom plugin type.
To register a new plugin-loader add this to package.json:
{
"mashroom": {
"plugins": [
{
"name": "My Custom Plugin Loader",
"type": "plugin-loader",
"bootstrap": "./dist/mashroom-bootstrap",
"loads": "my-custom-type",
"defaultConfig": {
"myProperty": "foo"
}
}
]
}
}
After that all plugins of type my-custom-type will be passed to your custom loader instantiated by the bootstrap script:
import type {
MashroomPluginLoader, MashroomPlugin, MashroomPluginConfig, MashroomPluginContext,
MashroomPluginLoaderPluginBootstrapFunction
} from 'mashroom/type-definitions';
class MyPluginLoader implements MashroomPluginLoader {
get name(): string {
return 'My Plugin Loader';
}
generateMinimumConfig(plugin: MashroomPlugin) {
return {};
}
async load(plugin: MashroomPlugin, config: MashroomPluginConfig, context: MashroomPluginContext) {
// TODO
}
async unload(plugin: MashroomPlugin) {
// TODO
}
}
const myPluginLoaderPlugin: MashroomPluginLoaderPluginBootstrapFunction = (pluginName, pluginConfig, pluginContextHolder) => {
return new MyPluginLoader();
};
export default myPluginLoaderPlugin;
Registers a Express webapp that will be available at a given path.
To register a web-app plugin add this to package.json:
{
"mashroom": {
"plugins": [
{
"name": "My Webapp",
"type": "web-app",
"bootstrap": "./dist/mashroom-bootstrap.js",
"defaultConfig": {
"path": "/my/webapp",
"myProperty": "foo"
}
}
]
}
}
And the bootstrap just returns the Express webapp:
import webapp from './webapp';
import type {MashroomWebAppPluginBootstrapFunction} from '@mashroom/mashroom/type-definitions';
const bootstrap: MashroomWebAppPluginBootstrapFunction = async () => {
return webapp;
};
export default bootstrap;
Additional handlers
It is also possible to return handlers in the bootstrap. Currently there is only one:
Example:
const bootstrap: MashroomWebAppPluginBootstrapFunction = async () => {
return {
expressApp: webapp,
upgradeHandler: (request: IncomingMessageWithContext, socket: Socket, head: Buffer) => {
// TODO
},
};
};
Registers a Express Router (a REST API) and makes it available at a given path.
To register a API plugin add this to package.json:
{
"mashroom": {
"plugins": [
{
"name": "My REST API",
"type": "api",
"bootstrap": "./dist/mashroom-bootstrap.js",
"defaultConfig": {
"path": "/my/api",
"myProperty": "foo"
}
}
]
}
}
And the bootstrap just returns the Express router:
const express = require('express');
const router = express.Router();
router.get('/', (req, res) => {
// ...
});
import type {MashroomApiPluginBootstrapFunction} from '@mashroom/mashroom/type-definitions';
const bootstrap: MashroomApiPluginBootstrapFunction = async () => {
return router;
};
export default bootstrap;
Registers a Express middleware and adds it to the global middleware stack.
To register a middleware plugin add this to package.json:
{
"mashroom": {
"plugins": [{
"name": "My Middleware",
"type": "middleware",
"bootstrap": "./dist/mashroom-bootstrap.js",
"defaultConfig": {
"order": 500,
"myProperty": "foo"
}
}]
}
}
And the bootstrap just returns the Express middleware:
import MyMiddleware from './MyMiddleware';
import type {MashroomMiddlewarePluginBootstrapFunction} from '@mashroom/mashroom/type-definitions';
const bootstrap: MashroomMiddlewarePluginBootstrapFunction = async (pluginName, pluginConfig, pluginContextHolder) => {
const pluginContext = pluginContextHolder.getPluginContext();
const middleware = new MyMiddleware(pluginConfig.myProperty, pluginContext.loggerFactory);
return middleware.middleware();
};
export default bootstrap;
Registers some static resources and exposes it at a given path (via Express static).
To register a static plugin add this to package.json:
{
"mashroom": {
"plugins": [{
"name": "My Documents",
"type": "static",
"documentRoot": "./my-documents",
"defaultConfig": {
"path": "/my/docs"
}
}]
}
}
Used to load arbitrary shared code that can be loaded via pluginContext.
To register a service plugin add this to package.json:
{
"mashroom": {
"plugins": [{
"name": "My services Services",
"type": "services",
"namespace": "myNamespace",
"bootstrap": "./dist/mashroom-bootstrap.js",
"defaultConfig": {
}
}]
}
}
The bootstrap will just return an object with a bunch of services:
import MyService from './MyService';
import type {MashroomServicesPluginBootstrapFunction} from '@mashroom/mashroom/type-definitions';
const bootstrap: MashroomServicesPluginBootstrapFunction = async (pluginName, pluginConfig, pluginContextHolder) => {
const pluginContext = pluginContextHolder.getPluginContext();
const service = new MyService(pluginContext.loggerFactory);
return {
service,
};
};
export default bootstrap;
A simple plugin to register an arbitrary web-app or static plugin as panel in the Admin UI.
To register an admin-ui-integration plugin add this to package.json:
{
"mashroom": {
"plugins": [{
"name": "My Admin Panel Integration",
"type": "admin-ui-integration",
"requires": [
"My Admin Panel"
],
"target": "My Admin Panel",
"defaultConfig": {
"menuTitle": "My Admin Panel",
"path": "/my-admin-panel",
"height": "80vh",
"weight": 10000
}
}]
}
}
parent.postMessage({ height: contentHeight + 20 }, "*");
1.9.0 (October 18, 2021)
"k8sNamespacesLabelSelector": "environment=development,tier=frontend",
"k8sNamespaces": null,
"k8sServiceLabelSelector": "microfrontend=true,channel!=alpha"
"k8sNamespacesLabelSelector": "environment=development",
"k8sNamespaces": null,
"serviceNameFilter": "(microfrontend-)",
http://localhost:5050/portal/web/___/api/pages/test2/content?currentPageId=subpage1
Means: Give me the content (and scripts to launch/hydrate the Apps) for page test2, and I'm currently
on page subpage1, tell me if I need a full page load because the theme or something else outside
the content area is different.<div id="portal-app-{{appId}}" class="mashroom-portal-app-wrapper portal-app-{{safePluginName}}">
<div class="mashroom-portal-app-header">
<div class="mashroom-portal-app-header-title" data-replace-content="title">{{title}}</div>
</div>
<div class="mashroom-portal-app-host" data-replace-content="app">
{{#if appSSRHtml}}
{{{appSSRHtml}}}
{{else}}
<div class="mashroom-portal-app-loading"><span/></div>
{{/if}}
</div>
</div>
FAQs
Mashroom Server. Supports out of the box the following plugin types: 'web-app', 'api', 'middleware', 'static', 'services' and 'plugin-loader'.
The npm package @mashroom/mashroom receives a total of 38 weekly downloads. As such, @mashroom/mashroom popularity was classified as not popular.
We found that @mashroom/mashroom demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.