MRT Utilities

The @salesforce/mrt-utilities package provides middleware and utilities to simulate a deployed Managed Runtime (MRT) environment. Use it when building storefronts or apps that run on MRT so you can develop and test locally with the same request flow, proxy behavior, and static asset paths as in production.

When to use

• Local development of PWA Kit or other MRT-hosted apps: run an Express server that mimics MRT’s request processor, proxying, and static asset serving.
• Testing request processor logic and proxy configs before deploying to MRT.
• Streaming/SSR on Lambda: use the streaming subpath to adapt Express apps to AWS Lambda with response streaming and compression.

Prerequisites

• Node.js 22.16.0 or later
• Express 4.x or 5.x (peer dependency)

Installation

pnpm add @salesforce/mrt-utilities express
# or
npm install @salesforce/mrt-utilities express

Package exports

Export	Description
Main (@salesforce/mrt-utilities)	Middleware factories, isLocal, and re-exports from subpaths
Middleware (@salesforce/mrt-utilities/middleware)	MRT-style Express middleware and ProxyConfig type
Metrics (@salesforce/mrt-utilities/metrics)	Metrics sending for MRT (e.g. CloudWatch)
Streaming (@salesforce/mrt-utilities/streaming)	Lambda streaming adapter, Express request/response helpers, compression config

Basic setup

Wire the middleware in the order your app needs. Use createMRTCommonMiddleware and createMRTCleanUpMiddleware in all environments (local and deployed). For local-only behavior (request processor, proxies, static assets), guard with isLocal().

import express from 'express';
import {
  createMRTProxyMiddlewares,
  createMRTRequestProcessorMiddleware,
  createMRTStaticAssetServingMiddleware,
  createMRTCommonMiddleware,
  createMRTCleanUpMiddleware,
  isLocal,
} from '@salesforce/mrt-utilities';

const app = express();
app.disable('x-powered-by');

// Top-most: set up MRT-style headers
app.use(createMRTCommonMiddleware());

if (isLocal()) {
  const requestProcessorPath = 'path/to/request-processor.js';
  const proxyConfigs = [{host: 'https://example.com', path: 'api'}];

  app.use(createMRTRequestProcessorMiddleware(requestProcessorPath, proxyConfigs));

  const mrtProxies = createMRTProxyMiddlewares(proxyConfigs);
  mrtProxies.forEach(({path, fn}) => app.use(path, fn));

  const staticAssetDir = 'path/to/static';
  app.use(
    `/mobify/bundle/${process.env.BUNDLE_ID || '1'}/static/`,
    createMRTStaticAssetServingMiddleware(staticAssetDir),
  );
}

// Clean up headers and set remaining values
app.use(createMRTCleanUpMiddleware());

Middleware

createMRTCommonMiddleware()

Sets headers and other request/response behavior to match MRT. Use in all environments (local and deployed). Mount at the top of your middleware stack.

createMRTRequestProcessorMiddleware(requestProcessorPath, proxyConfigs)

• requestProcessorPath: Path to your request processor module (e.g. request-processor.js).
• proxyConfigs: Array of { host, path } used for proxy and request-processor routing.

Runs your request processor in the local pipeline so routing and SSR behave like MRT.

createMRTProxyMiddlewares(proxyConfigs)

Returns an array of { path, fn } for mounting proxy middleware. Each entry proxies under /mobify/proxy/<path> to the configured host. Mount each with app.use(path, fn).

ProxyConfig (from @salesforce/mrt-utilities/middleware):

interface ProxyConfig {
  host: string; // e.g. 'https://example.com'
  path: string; // e.g. 'api'
}

createMRTStaticAssetServingMiddleware(staticAssetDir)

Serves static files from staticAssetDir under the MRT bundle static path. Use the same path pattern as in production (e.g. /mobify/bundle/<id>/static/).

createMRTCleanUpMiddleware()

Removes internal MRT headers and sets any remaining response headers. Use in all environments (local and deployed). Mount after your app logic and before sending the response.

Environment detection

isLocal() returns true when not running in AWS Lambda (i.e. when AWS_LAMBDA_FUNCTION_NAME is not set). Use it to enable local-only middleware (request processor, proxies, local static assets).

import {isLocal} from '@salesforce/mrt-utilities';

if (isLocal()) {
  // Use local request processor, proxies, static assets
}

Streaming (Lambda)

For MRT’s Lambda runtime with streaming responses (e.g. SSR), use the streaming subpath:

import {createStreamingLambdaAdapter, type CompressionConfig} from '@salesforce/mrt-utilities/streaming';

• createStreamingLambdaAdapter: Wraps your Express app so it can be invoked from Lambda with streaming support.
• CompressionConfig: Options for response compression (e.g. encoding, quality).

See the package source and tests for full adapter usage.

Tuning Brotli compression

For streamed responses, Brotli defaults to a runtime-appropriate quality (6) and periodically flushes compressed output so bytes reach the client sooner. This can be tuned with environment variables:

• MRT_BROTLI_COMPRESSION_QUALITY: Brotli quality level, 0–11 (defaults to 6). Higher values compress more but cost more CPU. Values outside the valid range are ignored.
• MRT_BROTLI_FLUSH_THRESHOLD_BYTES: Number of uncompressed bytes to buffer before forcing a Brotli flush (defaults to 32768). Must be a positive integer; other values are ignored.
• MRT_BROTLI_CHUNKING_ENABLED: Periodic flushing ("chunking") of Brotli output is enabled by default. Set to false to disable it and let Brotli buffer output until the response ends.

An explicit Brotli quality set via CompressionConfig.options.params takes precedence over MRT_BROTLI_COMPRESSION_QUALITY.

Metrics

For sending metrics (e.g. to CloudWatch) in an MRT-compatible way:

import {MetricsSender} from '@salesforce/mrt-utilities/metrics';

Use when you need to emit metrics from the same process that serves requests (e.g. custom middleware or request processor).

Data Store In Development

The production MRT data store is not available during local development because it depends on deployed runtime infrastructure. @salesforce/mrt-utilities provides an equivalent development data-store implementation for local use.

To use that local equivalent, import from the data-store subpath and run Node with the dev-data-store condition:

node --conditions dev-data-store server.js

import {DataStore} from '@salesforce/mrt-utilities/data-store';

const store = DataStore.getDataStore();
const entry = await store.getEntry('custom-global-preferences');

Provide local data-store values through environment variables:

• MRT_DATA_STORE_DEFAULTS: JSON map of data-store keys to object values
• MRT_DATA_STORE_WARN_ON_MISSING: set to false to suppress missing-key warnings

Example:

export MRT_DATA_STORE_DEFAULTS='{"custom-global-preferences":{"featureFlag":true}}'
export MRT_DATA_STORE_WARN_ON_MISSING=true

The development pseudo store keeps production parity for missing keys and throws DataStoreNotFoundError when a key is not found.

Related

• MRT CLI commands — manage MRT projects, environments, and bundles from the CLI.
• Storefront Next — environment variables, logs, deployments, and assistant support.