{"id":17973,"library":"talkback","title":"Talkback HTTP Proxy","description":"Talkback is a Node.js HTTP proxy library that records and plays back HTTP requests, effectively acting as a 'VCR for HTTP'. It is currently at version 4.2.0 and appears to be actively maintained, with recent updates and continuous integration setup on GitHub. This tool is designed to accelerate integration tests by allowing applications to run against mocked servers, eliminating the need for live external service calls during development or CI/CD pipelines. A key differentiator is its flexibility: it can be run as a standalone HTTP server in its own process or integrated directly into an application as a request handler. It automatically records new requests when no matching tape is found and then serves those recorded 'tapes' for subsequent, identical requests, providing consistent and fast responses for testing and development environments.","status":"active","version":"4.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/ijpiantanida/talkback","tags":["javascript","http-proxy","record","vcr","playback"],"install":[{"cmd":"npm install talkback","lang":"bash","label":"npm"},{"cmd":"yarn add talkback","lang":"bash","label":"yarn"},{"cmd":"pnpm add talkback","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"While CommonJS `require` is shown in the README, `import` is the recommended pattern for modern Node.js (`>=18`) and TypeScript projects. Talkback supports both.","wrong":"const talkback = require('talkback');","symbol":"talkback","correct":"import talkback from 'talkback';"},{"note":"Enums like `RecordMode` are exposed as properties of the main `talkback` export, not as top-level named exports.","wrong":"import { Options } from 'talkback';\nconst recordMode = Options.RecordMode.NEW;","symbol":"talkback.Options.RecordMode","correct":"import talkback from 'talkback';\nconst recordMode = talkback.Options.RecordMode.NEW;"},{"note":"`requestHandler` is a method on the default `talkback` export, not a direct named export.","wrong":"import { requestHandler } from 'talkback';","symbol":"talkback.requestHandler","correct":"import talkback from 'talkback';\nconst handler = await talkback.requestHandler(opts);"}],"quickstart":{"code":"import talkback from 'talkback';\nimport path from 'path';\n\nconst tapesPath = path.resolve(process.cwd(), './my-tapes');\n\nconst opts = {\n  host: 'https://api.myapp.com/foo',\n  record: talkback.Options.RecordMode.NEW,\n  port: 5544,\n  path: tapesPath,\n  // Optional: customize http client for proxying\n  httpClient: {\n    timeout: 30000 // 30 seconds\n  }\n};\n\nconst server = talkback(opts);\n\nserver.start(() => {\n  console.log('Talkback server started on port 5544, proxying to https://api.myapp.com/foo');\n  console.log(`Tapes will be stored in: ${tapesPath}`);\n});\n\n// Example of how to close the server (e.g., in tests)\nprocess.on('SIGINT', () => {\n  server.close(() => {\n    console.log('Talkback server closed.');\n    process.exit(0);\n  });\n});","lang":"typescript","description":"Sets up and starts a Talkback HTTP proxy server, configuring it to record new requests and save tapes to a specified directory."},"warnings":[{"fix":"Review the documentation for `RecordMode` and `FallbackMode`. For development, `RecordMode.NEW` is often a good starting point to automatically create tapes. For CI, consider `FallbackMode.ERROR` for strict failure on missing tapes.","message":"Carefully configure `record` and `fallbackMode` options. If `record` is disabled (e.g., `RecordMode.DISABLED`) and `fallbackMode` is set to `FallbackMode.NOT_FOUND`, any unmatched requests will result in a 404. This is intentional for strict testing but can cause unexpected failures if tapes are incomplete or request matching is too strict.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Start with default `ignoreHeaders` and incrementally add specific headers to `allowHeaders` only if they are truly part of the request's unique identifier. Ensure `content-type` and `content-encoding` are considered if body decoding is necessary.","message":"Incorrect configuration of `allowHeaders` or `ignoreHeaders` can lead to tapes not being matched correctly. Headers are crucial for request uniqueness, and misconfigured lists can either ignore important headers (leading to false positives) or include volatile headers (leading to false negatives).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If encountering certificate errors, configure the `https` option in Talkback to provide custom CA certificates (`ca`), client certificates (`cert`, `key`), or disable strict SSL verification (`rejectUnauthorized: false` for testing, but use with caution in production-like environments). Refer to Node.js `https` module documentation for details.","message":"Proxying HTTPS traffic (i.e., when the `host` is `https://...`) requires proper handling of SSL certificates. Self-signed certificates or specific corporate proxy setups might cause `DEPTH_ZERO_SELF_SIGNED_CERT` or similar errors if Node.js does not trust the upstream certificate.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade your Node.js environment to version 18 or newer. Use a Node.js version manager like `nvm` to easily switch and manage Node.js versions.","message":"Talkback version 4.x requires Node.js version 18 or higher. Older Node.js versions (e.g., 16.x) are no longer supported due to updates in underlying dependencies or language features.","severity":"breaking","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Change the `port` option in your Talkback configuration to an available port, or ensure no other process is running on the desired port before starting Talkback. You can find and kill processes using `lsof -i :<port>` (macOS/Linux) or `netstat -ano | findstr :<port>` (Windows).","cause":"The specified port (e.g., 5544) for the Talkback server is already being used by another process.","error":"Error: listen EADDRINUSE: address already in use :::5544"},{"fix":"Ensure you are using the correct import syntax for your project's module system. If using ESM (`type: \"module\"` in `package.json`), use `import talkback from 'talkback';`. If using CommonJS, use `const talkback = require('talkback');`. The provided example uses `require` but modern Node.js setups may prefer `import`.","cause":"This error often occurs when attempting to call `talkback()` as a function after a CommonJS `require()` when the package might be primarily designed for ESM, or vice-versa, or if the import path is incorrect.","error":"TypeError: talkback is not a function"},{"fix":"Ensure the directory specified in the `path` option (`./my-tapes` in the example) exists and that the Node.js process has appropriate read/write permissions for that directory. You might need to create the directory programmatically or manually before starting Talkback, e.g., `fs.mkdirSync(tapesPath, { recursive: true });`","cause":"Talkback's `path` option points to a directory that does not exist or is inaccessible for reading/writing tapes.","error":"Error: ENOTDIR: not a directory, open './my-tapes/...' or Error: ENOENT: no such file or directory, stat './my-tapes/'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}