{"id":17568,"library":"datahub-proxy-middleware","title":"DataHub Proxy Middleware","description":"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.","status":"active","version":"5.0.3","language":"javascript","source_language":"en","source_url":"git://github.com/macacajs/datahub-proxy-middleware","tags":["javascript","datahub","middleware"],"install":[{"cmd":"npm install datahub-proxy-middleware","lang":"bash","label":"npm"},{"cmd":"yarn add datahub-proxy-middleware","lang":"bash","label":"yarn"},{"cmd":"pnpm add datahub-proxy-middleware","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is a proxy for the macaca-datahub server; it's essential for providing the mock data backend.","package":"macaca-datahub","optional":false},{"reason":"The middleware is designed to integrate with Express.js or Connect-style `app` instances. While not a direct dependency, it's implicitly required for typical usage.","package":"express","optional":true}],"imports":[{"note":"This package primarily uses CommonJS `require`. There is no official ESM export.","wrong":"import datahubMiddleware from 'datahub-proxy-middleware';","symbol":"datahubMiddleware","correct":"const datahubMiddleware = require('datahub-proxy-middleware');"}],"quickstart":{"code":"const express = require('express');\nconst datahubMiddleware = require('datahub-proxy-middleware');\nconst DataHub = require('macaca-datahub');\n\nconst app = express();\nconst port = 3000;\n\n// Minimal DataHub configuration for quickstart\nconst datahubPort = 5678;\nconst datahubConfig = {\n  port: datahubPort,\n  hostname: '127.0.0.1',\n  proxy: {\n    '/api': {\n      hub: 'my_project_hub',\n      port: datahubPort,\n      hostname: 'localhost',\n      pathOptions: {\n        start: true\n      }\n    },\n  },\n  // In a real scenario, you'd have actual data in a store\n  store: require('path').join(__dirname, 'data'),\n  showBoard: false // Set to true to see the DataHub UI\n};\n\n// Initialize and start DataHub server\nconst datahubInstance = new DataHub({\n  port: datahubConfig.port,\n});\ndatahubInstance.startServer(datahubConfig).then(() => {\n  console.log(`DataHub server ready on ${datahubConfig.hostname}:${datahubConfig.port}`);\n});\n\n// Apply datahub-proxy-middleware to your Express app\napp.use(datahubMiddleware(app)(datahubConfig));\n\n// Example route (will be proxied by datahubMiddleware if matching /api)\napp.get('/api/users', (req, res) => {\n  res.json({ message: 'This should be mocked by DataHub!' });\n});\n\n// Fallback for non-proxied routes\napp.get('/', (req, res) => {\n  res.send('Hello from Express!');\n});\n\napp.listen(port, () => {\n  console.log(`Express app listening at http://localhost:${port}`);\n  console.log('Try accessing http://localhost:3000/api/users (requires DataHub to serve mock data)');\n});","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure that the `app` object passed to `datahubMiddleware(app)` is a valid Express or Connect application instance, typically created via `const app = express();`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Ensure `app` is initialized with `const app = express();` or similar before passing it to `datahubMiddleware(app)`.","cause":"`app` object passed to the middleware is not a valid Express or Connect application instance.","error":"TypeError: app.use is not a function"},{"fix":"Verify that your `macaca-datahub` instance is running and listening on the correct `port` and `hostname` defined in `datahubConfig.proxy`.","cause":"The `macaca-datahub` server is not running or is not accessible at the specified `port` and `hostname` in the `datahubConfig`.","error":"Proxy error: connect ECONNREFUSED 127.0.0.1:5678"},{"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.","cause":"DataHub is running, but it does not have mock data configured for the requested path or hub.","error":"No mock data found for path: /api/users"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}