{"id":14068,"library":"stubborn-server","title":"Node.js Stub Server","description":"Stubborn Server is a Node.js library designed to create flexible stub servers for development and testing environments. It currently maintains a stable version, 2.0.1, and has a release cadence that addresses dependency updates, bug fixes, and feature enhancements as needed, with major breaking changes typically bundled into new major versions. Its core functionality includes serving static JSON mocks, handling dynamic requests with Express-based handlers, managing an in-memory database with namespace support, and providing mechanisms for aliasing mock responses and defining fallback routes (static files, proxying to other targets, or reusing existing mocks). A key differentiator is its integration with Express, allowing users to attach custom Express middleware and handlers directly, offering significant flexibility over purely configuration-driven mocking solutions. It's well-suited for integration testing and rapid front-end development against evolving APIs.","status":"active","version":"2.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/zeachco/stubborn-server","tags":["javascript","stub","mock","server","node","test"],"install":[{"cmd":"npm install stubborn-server","lang":"bash","label":"npm"},{"cmd":"yarn add stubborn-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add stubborn-server","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package exposes a function as its default CommonJS export. It is not an ES module.","wrong":"import stubbornServer from 'stubborn-server';","symbol":"stubbornServer","correct":"const stubbornServer = require('stubborn-server');"},{"note":"The `require('stubborn-server')` call returns a function that must be invoked to create a server instance.","wrong":"const stub = require('stubborn-server');","symbol":"stub","correct":"const stub = stubbornServer();"},{"note":"Configuration is passed as an object to `stub.start()` or loaded from `stubborn.js`/`stubborn.json`. There is no direct TypeScript type export mentioned in the README.","symbol":"StubbornServerConfig","correct":"// No direct import, configure via object or file\nconst config = {\n  logMode: 'all',\n  servePort: 8059\n};"}],"quickstart":{"code":"const stubbornServer = require('stubborn-server');\n\n// Define your server configuration\nconst config = {\n  logMode: 'all', // can be 'all', 'info', 'mock', 'warn', 'error' or 'none'\n  namespace: '', // help switching between different scenarios\n  pathToMocks: './mock-examples', // mock folder relative path\n  servePort: 8059,\n  includes: [], // List of files into the mock folder where the express app will be exposed for custom handling\n  fallbacks: [\n    { \n      url: '/*',\n      target: `http://localhost:${process.env.FALLBACK_PORT ?? 3000}` // Example fallback to another server\n    }\n  ]\n};\n\n// Create an instance of the stubborn server\nconst stub = stubbornServer();\n\n// Optional: Attach custom Express handlers directly before starting\nstub.app.use('/api/hello', (req, res) => {\n  res.json({ message: 'Hello from custom handler!', method: req.method });\n});\n\n// Start the server with the defined configuration\nstub.start(config);\n\nconsole.log(`Stubborn Server started on port ${config.servePort}`);\n\n// Example of changing configuration during runtime (e.g., for different test scenarios)\n// setTimeout(() => {\n//   console.log('Switching namespace to \"alt\"');\n//   stub.config.set({\n//     namespace: 'alt'\n//   });\n// }, 5000);\n\n// To stop the server (e.g., in a test teardown)\n// setTimeout(() => {\n//   console.log('Stopping server...');\n//   stub.stop();\n// }, 10000);","lang":"javascript","description":"This quickstart initializes and starts a stubborn server instance with a basic configuration, including an example of attaching a custom Express handler. It demonstrates how to define server settings, programmatically start the server, and includes comments on dynamic configuration changes and stopping the server."},"warnings":[{"fix":"Ensure your Node.js environment is version 10 or higher. Upgrade Node.js if necessary.","message":"Version 2.0.0 introduced a hard dependency on Node.js version 10 or greater. Running on older Node.js versions will result in an error.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Refactor your code to create a new `stubbornServer()` instance for each server you intend to run and manage its configuration and lifecycle independently. The `stubbornServer()` call returns a function which must then be invoked `stub = stubbornServer();`.","message":"Version 1.0.0 introduced significant API changes to support multiple independent server instances. Configuration is now isolated per instance, and each instance spawns its own Express server. Direct access to a global server instance is no longer possible.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Always use a current Long Term Support (LTS) version of Node.js with stubborn-server to ensure compatibility and stability.","message":"Version 1.0.0 also dropped support for Node.js versions older than the then-current LTS. While not explicitly specified in the release notes, this often implies strict adherence to currently maintained Node.js LTS lines.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Use `const stubbornServer = require('stubborn-server');` for importing the library.","message":"Stubborn Server primarily functions as a CommonJS module. Attempting to use ES module `import` syntax will fail at runtime unless your environment is configured for interoperability (e.g., via a transpiler or specific Node.js `--experimental-modules` flags).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always initialize the server with `const stub = stubbornServer();` before calling methods like `stub.start()` or `stub.stop()`.","message":"The `stubborn-server` package requires its main export, which is a function, to be invoked to create a server instance. Directly calling methods like `start()` on the imported module will result in a `TypeError`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'2.0.1':27 'address':34 'alias':83 'allow':108 'api':144 'attach':111 'base':68 'break':46 'bug':37 'bundl':49 'cadenc':32 'chang':47 'configur':124 'configuration-driven':123 'core':55 'creat':12 'current':22 'custom':112 'databas':75 'defin':87 'depend':35 'design':10 'develop':17,141 'differenti':102 'direct':117 'driven':125 'dynam':63 'end':140 'enhanc':41 'environ':20 'evolv':143 'exist':98 'express':67,107,113 'express-bas':66 'fallback':88 'featur':40 'file':91 'fix':38 'flexibl':13,120 'front':139 'front-end':138 'function':56 'handl':62 'handler':69,116 'in-memori':72 'includ':57 'integr':105,134 'javascript':145 'json':60 'key':101 'librari':9 'maintain':23 'major':45,52 'manag':70 'mechan':81 'memori':74 'middlewar':114 'mock':61,84,99,126,147 'namespac':77 'need':43 'new':51 'node':149 'node.js':1,8 'offer':118 'provid':80 'proxi':92 'pure':122 'rapid':137 'releas':31 'request':64 'respons':85 'reus':97 'rout':89 'serv':58 'server':3,5,15,148 'signific':119 'solut':127 'stabl':25 'static':59,90 'stub':2,14,146 'stubborn':4 'suit':132 'support':78 'target':95 'test':19,135,150 'typic':48 'updat':36 'user':109 'version':26,53 'well':131 'well-suit':130","created_at":"2026-04-20T01:57:46.286741+00:00","updated_at":"2026-04-20T01:57:46.286741+00:00","problems":[{"fix":"You need to invoke the imported function to get a server instance: `const stub = require('stubborn-server')();` then `stub.start();`","cause":"Attempting to call `start()` directly on the `require('stubborn-server')` return value instead of first instantiating the server.","error":"TypeError: stubbornServer.start is not a function"},{"fix":"Upgrade your Node.js environment to version 10 or newer (e.g., use `nvm install 16` and `nvm use 16`).","cause":"Running the package on a Node.js version older than 10.x, which is explicitly unsupported since v2.0.0.","error":"Error: stubborn-server requires Node.js version >=10"},{"fix":"Change your import statement to use CommonJS `require()`: `const stubbornServer = require('stubborn-server');`.","cause":"Using ES module `import` syntax to load a package that is published as a CommonJS module.","error":"SyntaxError: Unexpected token 'export' (for import { Name } from 'stubborn-server')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"stubborn-server","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/zeachco/stubborn-server","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/stubborn-server","openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing","web-framework","http-networking","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}