DataHub Proxy Middleware

5.0.3 verified Thu Apr 23 auth: no javascript

datahub-proxy-middleware is an Express/Connect-compatible HTTP server middleware designed to proxy API requests to a Macaca.js DataHub instance. It facilitates API mocking and data management during development by allowing developers to define flexible proxy rules that redirect specific paths to a running DataHub server for mock data retrieval. The current stable version, 5.0.3, was released in March 2024, indicating active maintenance within the Macaca.js ecosystem. Key differentiators include its tight integration with `macaca-datahub`, robust configuration options for defining proxy routes (e.g., dynamic ports, hostnames, and path matching with `@macaca-project/path-to-regexp`), and its suitability for development environments, particularly when integrated with tools like `webpack-dev-server` to provide mock data without requiring a live backend.

Common errors

error TypeError: app.use is not a function ↓

cause `app` object passed to the middleware is not a valid Express or Connect application instance.

fix

Ensure app is initialized with const app = express(); or similar before passing it to datahubMiddleware(app).

error Proxy error: connect ECONNREFUSED 127.0.0.1:5678 ↓

cause The `macaca-datahub` server is not running or is not accessible at the specified `port` and `hostname` in the `datahubConfig`.

fix

Verify that your macaca-datahub instance is running and listening on the correct port and hostname defined in datahubConfig.proxy.

error No mock data found for path: /api/users ↓

cause DataHub is running, but it does not have mock data configured for the requested path or hub.

fix

Ensure that your macaca-datahub instance has the correct 'hub' activated and that mock data for the requested API paths (e.g., /api/users) is defined in your DataHub store.

Warnings

breaking The underlying `path-to-regexp` library, which `datahub-proxy-middleware` utilizes for route matching, introduced breaking changes in its version 6. Users configuring advanced `pathOptions` should consult the `pillarjs/path-to-regexp` v6 documentation to ensure their configurations are compatible and to avoid unexpected routing behavior. ↓

fix Review the official documentation for `pillarjs/path-to-regexp` version 6 for changes in syntax, options, and behavior related to path matching. Adjust `pathOptions` in your `datahubConfig` accordingly.

gotcha This middleware is designed for CommonJS environments using `require()`. Attempting to use ES module `import` syntax directly for `datahub-proxy-middleware` can lead to runtime errors, as it does not explicitly provide an ESM export. ↓

fix Always use `const datahubMiddleware = require('datahub-proxy-middleware');` when importing the package. If using in an ES module context, consider a transpilation step or a dynamic `import()` if absolutely necessary.

gotcha The middleware expects an Express-like `app` object. If `app` is not correctly initialized or is not a compatible server instance (e.g., missing `app.use` method), the middleware will fail to attach. ↓

fix Ensure that the `app` object passed to `datahubMiddleware(app)` is a valid Express or Connect application instance, typically created via `const app = express();`.

Install

npm install datahub-proxy-middleware

yarn add datahub-proxy-middleware

pnpm add datahub-proxy-middleware

Imports

datahubMiddleware

wrong

import datahubMiddleware from 'datahub-proxy-middleware';

correct

const datahubMiddleware = require('datahub-proxy-middleware');

This package primarily uses CommonJS `require`. There is no official ESM export.

Quickstart

This quickstart demonstrates setting up an Express server with `datahub-proxy-middleware` to proxy API requests to a `macaca-datahub` instance. It initializes both DataHub and the Express application, showing how to integrate the middleware for local development with mocked APIs.

const express = require('express');
const datahubMiddleware = require('datahub-proxy-middleware');
const DataHub = require('macaca-datahub');

const app = express();
const port = 3000;

// Minimal DataHub configuration for quickstart
const datahubPort = 5678;
const datahubConfig = {
  port: datahubPort,
  hostname: '127.0.0.1',
  proxy: {
    '/api': {
      hub: 'my_project_hub',
      port: datahubPort,
      hostname: 'localhost',
      pathOptions: {
        start: true
      }
    },
  },
  // In a real scenario, you'd have actual data in a store
  store: require('path').join(__dirname, 'data'),
  showBoard: false // Set to true to see the DataHub UI
};

// Initialize and start DataHub server
const datahubInstance = new DataHub({
  port: datahubConfig.port,
});
datahubInstance.startServer(datahubConfig).then(() => {
  console.log(`DataHub server ready on ${datahubConfig.hostname}:${datahubConfig.port}`);
});

// Apply datahub-proxy-middleware to your Express app
app.use(datahubMiddleware(app)(datahubConfig));

// Example route (will be proxied by datahubMiddleware if matching /api)
app.get('/api/users', (req, res) => {
  res.json({ message: 'This should be mocked by DataHub!' });
});

// Fallback for non-proxied routes
app.get('/', (req, res) => {
  res.send('Hello from Express!');
});

app.listen(port, () => {
  console.log(`Express app listening at http://localhost:${port}`);
  console.log('Try accessing http://localhost:3000/api/users (requires DataHub to serve mock data)');
});