Registry / devops / with-server

with-server

JSON →
library2.1.0jsnpmunverified

The `with-server` package is a command-line utility and programmatic API designed to orchestrate local server startup, command execution (typically end-to-end tests), and server shutdown. It automatically handles port allocation via the `$PORT` environment variable, waits for the server to become ready, and exposes `$SERVER_URL` to the executed command. It offers options to specify the server's start script and control output redirection. The current stable version is 2.1.0, with releases appearing infrequently, driven by feature additions or critical maintenance, such as the major Node.js version bump in v2.0.0. It's a focused tool for e2e testing workflows, abstracting away the complexities of server lifecycle management during test runs, differentiating itself by its simplicity and direct integration with npm scripts.

devopstesting
npm install with-server
github ↗package ↗
INSTALL
IMPORT
SIG · WITH-SERVER
W
with-server
devopsjavascriptv2.1.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

withServer
✓ const withServer = require("with-server");
✗ import withServer from 'with-server';
The package is primarily CommonJS (`type: commonjs`). Direct ESM imports might require specific import paths or bundler configuration to resolve correctly.

Demonstrates programmatic usage of `with-server` to run a test command (e.g., Cypress) against a local server, specifying the server start script and output redirection, and handling the exit code.

const withServer = require("with-server"); async function runTests() { console.log('Starting server and running tests...'); try { const exitCode = await withServer("cypress run", { run: "start", // Assuming 'npm start' is the command to launch your server redirect: "stderr", // Redirect server logs to stderr to keep test output clean // Additional options like 'port' can be specified if you need a fixed port }); console.log(`Test command exited with code: ${exitCode}`); process.exit(exitCode); } catch (error) { console.error('An error occurred:', error.message); process.exit(1); } } // Example package.json script for demonstration: // "scripts": { // "start": "node server.js", // "test:e2e": "node run-tests.js" // } // Where server.js might look like: // const http = require('http'); // const port = process.env.PORT || 3000; // http.createServer((req, res) => res.end('Hello from server')).listen(port, () => console.log(`Server listening on port ${port}`)); runTests();
with-server --version
Debug
Known issues
breakingVersion 2.0.0 dropped support for Node.js 12 and 14. The package now requires Node.js version 16 or newer.
fix
Upgrade your Node.js environment to version 16 or later. Check your `package.json` `engines` field and CI/CD configurations.
affects: >=2.0.0
gotchaThe server process started by `with-server` *must* listen on the TCP port specified by the `$PORT` environment variable. If `$PORT` is not explicitly set, `with-server` will pick a free random port and expose it.
fix
Ensure your server script reads from `process.env.PORT` (e.g., `app.listen(process.env.PORT || 3000)`) or, if using a fixed port, pass it via the programmatic API or environment variable before `with-server` execution.
affects: >=1.0.0
gotchaBy default, the standard output (stdout) of the server process is redirected to stderr to prevent it from mixing with test output. This can make debugging server logs challenging if you're not aware of it.
fix
Use the `--redirect stdout` command-line option or `redirect: 'stdout'` in the programmatic API to write server output to stdout. Alternatively, use `--redirect null` or `redirect: 'null'` to silence server output completely.
affects: >=1.0.0
Errors
Common errors & fixes
Error: connect ECONNREFUSED 127.0.0.1:XXXX
The server process failed to start or did not listen on the expected port before the timeout, preventing `with-server` from establishing a connection.
fix
Verify your server's start script, ensure it's listening on `process.env.PORT`, and check for any startup errors in the server's output (redirect to stdout for debugging). Increase timeout if server takes long to start.
command not found: <your-test-command>
The test command specified (e.g., 'cypress') is not installed globally, not available in the local `node_modules/.bin` directory, or not properly configured in your `package.json` scripts.
fix
Ensure the test command is installed as a `devDependency` (e.g., `npm install cypress --save-dev`) and either run `with-server` via `npm scripts` or directly reference the local binary (e.g., `node_modules/.bin/cypress`).
Error: Cannot find module 'with-server'
The `with-server` package is not installed in your project's `node_modules` directory, or there's an issue with how it's being imported (e.g., trying to use `import` syntax in a CommonJS-only context without a bundler).
fix
Run `npm install with-server --save-dev` to install the package. If using ESM, ensure your setup correctly handles CJS module imports or consider bundling your code.
Upgrade
Version history
2.1.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
22 hits · last 30 days
node
19
Resources
githubhttps://github.com/cellular/with-server ↗
packagehttps://www.npmjs.com/package/with-server ↗
with-server — npm install with-server · libregistry