{"id":17549,"library":"connect-prism","title":"HTTP Traffic Recording, Mocking, and Proxying for Connect","description":"Connect-prism is a Node.js middleware designed to record, mock, and proxy HTTP traffic, primarily for front-end development and end-to-end testing of Single Page Applications (SPAs). It functions by integrating with the `connect` middleware framework, allowing developers to capture API responses, store them as JSON files, and then replay them locally, effectively caching backend interactions. The package supports four modes: 'record' (captures live responses), 'mock' (serves recorded responses), 'mock & record' (prioritizes mocks, records if not found), and 'proxy' (forwards requests to a target API). The current stable version, 1.0.21, was last published in early 2019, indicating an abandoned or minimally maintained status. Its key differentiators include its tight integration with `connect` servers for in-development mocking and its VCR-like approach to HTTP interaction capture, accelerating test suites and reducing reliance on live backend services during development. It decompresses gzipped/deflated responses for readable mock files.","status":"abandoned","version":"1.0.21","language":"javascript","source_language":"en","source_url":"https://github.com/seglo/connect-prism","tags":["javascript","mock","record","proxy","connect","middleware","stub","http","prism"],"install":[{"cmd":"npm install connect-prism","lang":"bash","label":"npm"},{"cmd":"yarn add connect-prism","lang":"bash","label":"yarn"},{"cmd":"pnpm add connect-prism","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core middleware framework that connect-prism integrates with. Essential for operation.","package":"connect","optional":false}],"imports":[{"note":"Connect-prism is a CommonJS module and primarily used with `require()`. ESM imports are not officially supported.","wrong":"import prism from 'connect-prism';","symbol":"prism","correct":"const prism = require('connect-prism');"},{"note":"The primary interaction is via the `prism.create()` factory method, which configures a prism instance.","wrong":"const prismInstance = new prism();","symbol":"create","correct":"const config = prism.create({ name: 'myApi', context: '/api', host: 'localhost', port: 8000 });"},{"note":"After configuring prism with `prism.create()`, the middleware function itself is exposed as `prism.middleware`.","wrong":"app.use(prism);","symbol":"middleware","correct":"app.use(prism.middleware);"}],"quickstart":{"code":"const connect = require('connect');\nconst http = require('http');\nconst path = require('path');\nconst prism = require('connect-prism');\nconst serveStatic = require('serve-static');\n\nconst app = connect();\nconst MOCKS_DIR = path.join(__dirname, 'mocks');\n\n// Configure connect-prism for an API endpoint\n// In 'record' mode, it will save responses to MOCKS_DIR\n// In 'mock' mode, it will serve responses from MOCKS_DIR\nprism.create({\n  name: 'myApi',\n  context: '/api',\n  host: 'jsonplaceholder.typicode.com',\n  port: 443,\n  https: true,\n  mode: process.env.PRISM_MODE || 'mock', // 'record', 'mock', 'proxy', 'mockrecord'\n  mocksPath: MOCKS_DIR,\n  // Optional: clear mocks on start in record/mockrecord modes\n  clearOnStart: process.env.PRISM_MODE === 'record' || process.env.PRISM_MODE === 'mockrecord',\n  // Log verbosity\n  verbose: true\n});\n\n// Add connect-prism middleware to the connect app\napp.use(prism.middleware);\n\n// Serve static files (e.g., your SPA index.html)\napp.use(serveStatic(path.join(__dirname, 'public')));\n\n// Example: create a simple public/index.html for demonstration\n// <!-- public/index.html -->\n// <script>\n//   fetch('/api/todos/1')\n//     .then(res => res.json())\n//     .then(data => console.log('API Response:', data))\n//     .catch(err => console.error('Fetch Error:', err));\n// </script>\n\nhttp.createServer(app).listen(3000, () => {\n  console.log('Connect-prism server running on http://localhost:3000');\n  console.log(`Prism mode: ${process.env.PRISM_MODE || 'mock'}`);\n  console.log(`Mocks directory: ${MOCKS_DIR}`);\n  console.log('To record: set PRISM_MODE=record, then access /api/todos/1 in browser.');\n  console.log('To mock: set PRISM_MODE=mock, ensure mocks are in place, then access /api/todos/1.');\n});\n","lang":"javascript","description":"This quickstart sets up a basic `connect` server with `connect-prism` middleware. It demonstrates how to configure prism to proxy requests to an external API (JSONPlaceholder), record responses to a local 'mocks' directory, or serve previously recorded mocks. It uses environment variables to switch between 'record' and 'mock' modes."},"warnings":[{"fix":"Consider migrating to actively maintained HTTP mocking libraries such as 'nock' (for Node.js tests) or 'MSW' (Mock Service Worker for browser/Node.js) which offer broader compatibility and active development.","message":"The package connect-prism is abandoned, with the last update over 7 years ago (v1.0.21 in Feb 2019). It targets Node.js >= 0.10.0 and relies on the `connect` framework, which may have compatibility issues with modern Node.js versions (e.g., 16+) or ESM-only projects. Expect no further updates, bug fixes, or security patches.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Verify directory permissions (`chmod 755 <mocks_path>`) and ensure the `mocksPath` configured exists and is writable by the user running the Node.js process.","message":"When using 'record' or 'mockrecord' modes, `connect-prism` writes mock files to the `mocksPath` directory. Ensure the Node.js process has appropriate write permissions to this directory, or recording will fail silently or with file system errors.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"For consistent mock usage, normalize requests where possible, or use the 'override' feature if manual control over mock responses for specific request variations is needed. Regularly review generated mock files to ensure desired behavior.","message":"The default mock file name generation for `connect-prism` is based on the request URL and headers. Small changes in request parameters or headers (e.g., query strings, user-agent) can lead to different mock files being generated or existing mocks not being found.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Ensure you have `const connect = require('connect');` and `const app = connect();` and that `app.use(prism.middleware);` is called after `prism.create({ ... });`.","cause":"This error typically occurs when attempting to use connect-prism's middleware without properly initializing a `connect` application or if `prism.middleware` is not correctly invoked after `prism.create()`.","error":"TypeError: Cannot read properties of undefined (reading 'use')"},{"fix":"Check and adjust the file system permissions for your `mocksPath` directory. For example, `chmod -R 777 /path/to/mocks` (for development, be cautious in production) or ensure the user running the Node.js application owns the directory.","cause":"The Node.js process does not have sufficient write permissions to the directory specified in `mocksPath` or its subdirectories, preventing connect-prism from saving recorded mocks.","error":"Error: EACCES: permission denied, open '/path/to/mocks/generated-mock-file.json'"},{"fix":"Double-check the `context` path to ensure it matches the API endpoint your application is calling. Verify `host`, `port`, and `https` settings accurately reflect the target API. Ensure `app.use(prism.middleware);` is positioned early enough in your `connect` middleware stack to intercept API requests.","cause":"This often happens due to incorrect configuration of `context`, `host`, `port`, or `https` in `prism.create()`, or the `connect-prism` middleware is not placed correctly in the `connect` server's middleware chain.","error":"Prism is not proxying requests or recording mocks as expected."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}