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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
soap
✓ import { soap } from 'express-soap';
✗ const soap = require('express-soap');
The primary named export for creating SOAP middleware. While CommonJS `require` works, ESM `import` is preferred in modern Node.js and TypeScript environments.
soap
✓ const { soap } = require('express-soap');
✗ import soap from 'express-soap';
CommonJS syntax for Node.js environments. Note that `express-soap` exports `soap` as a named export, not a default export.
SoapMiddlewareOptions
✓ import type { SoapMiddlewareOptions } from 'express-soap';
For TypeScript users, import the `SoapMiddlewareOptions` type to get proper type-checking for the middleware configuration object.
This quickstart sets up an Express server with two routes: a root HTML page and a SOAP endpoint. The SOAP endpoint exposes an 'Add' operation through a dynamically defined WSDL, demonstrating how to register a service and its methods.
import express from 'express';
import { soap } from 'express-soap';
const app = express();
const PORT = 8000;
// A minimal WSDL definition for demonstration purposes
const myWsdl = `<?xml version="1.0" encoding="UTF-8"?>
<definitions name="CalculatorService"
targetNamespace="http://www.examples.com/CalculatorService/"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:tns="http://www.examples.com/CalculatorService/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://schemas.xmlsoap.org/wsdl/">
<types>
<xsd:schema targetNamespace="http://www.examples.com/CalculatorService/">
<xsd:element name="AddRequest">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="a" type="xsd:int"/>
<xsd:element name="b" type="xsd:int"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="AddResponse">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="result" type="xsd:int"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
</types>
<message name="AddInput">
<part name="parameters" element="tns:AddRequest"/>
</message>
<message name="AddOutput">
<part name="parameters" element="tns:AddResponse"/>
</message>
<portType name="CalculatorPort">
<operation name="Add">
<input message="tns:AddInput"/>
<output message="tns:AddOutput"/>
</operation>
</portType>
<binding name="CalculatorBinding" type="tns:CalculatorPort">
<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="Add">
<soap:operation soapAction="Add"/>
<input>
<soap:body use="literal"/>
</input>
<output>
<soap:body use="literal"/>
</output>
</operation>
</binding>
<service name="CalculatorService">
<port name="CalculatorPort" binding="tns:CalculatorBinding">
<soap:address location="http://localhost:${PORT}/soap/calculator"/>
</port>
</service>
</definitions>`;
app.use('/soap/calculator', soap({
services: {
CalculatorService: {
CalculatorPort: {
Add: ({ a, b }, res) => {
console.log(`Received Add request: a=${a}, b=${b}`);
res({
result: a + b
});
}
}
}
},
wsdl: myWsdl
}));
app.get('/', (req, res) => {
res.send(`
<h1>Express SOAP Server Running</h1>
<p>SOAP endpoint at <a href="http://localhost:${PORT}/soap/calculator?wsdl">http://localhost:${PORT}/soap/calculator?wsdl</a></p>
<p>Try sending a SOAP request to calculate sum (e.g., using SoapUI or a client library).</p>
`);
});
app.listen(PORT, () => {
console.log(`Express SOAP server listening on port ${PORT}`);
console.log(`Access WSDL at http://localhost:${PORT}/soap/calculator?wsdl`);
});
Debug
Known issues
breaking`express-soap` has a peer dependency on `express` version `4.x`. While `express` v5 has reached beta, using it with `express-soap` may lead to compatibility issues or unexpected behavior, as the middleware explicitly targets the 4.x API.fixEnsure your project's `express` version is explicitly set to `^4.x.x` in `package.json`. If you must use Express v5, consider alternatives or contribute to `express-soap` for v5 compatibility.
affects: >=1.0.0
breakingAs `express-soap` is built upon `node-soap`, any breaking changes in `node-soap`'s API (especially regarding service definitions, options, or callback signatures) can implicitly affect `express-soap` users. `node-soap` has undergone several changes, including how security, WSDL parsing, and asynchronous operations are handled.fixBefore upgrading the `soap` peer dependency, consult the `node-soap` changelog (e.g., on its GitHub repository) for potential breaking changes relevant to your service implementations. Adapt your `express-soap` service definitions accordingly.
affects: >=0.45.0 (for peer dep `soap` in `express-soap` v1.x)
gotchaThe provided WSDL or XML definition must be valid and accurately reflect the service methods implemented. Small errors in the WSDL (e.g., incorrect namespaces, types, or operation definitions) can lead to the SOAP service failing to initialize or clients receiving SOAP faults.fixThoroughly validate your WSDL/XML schema using a WSDL validator or `node-soap`'s `describe()` method. Ensure that your `services` object structure precisely matches the operations and types defined in your WSDL. If using dynamic WSDL, confirm it is generated correctly.
affects: *
gotchaSOAP service methods must correctly invoke the `res` callback to send a response back to the client. If `res()` is not called, the SOAP client will typically experience a timeout, leading to an unresponsive service. This applies even for 'one-way' operations where `node-soap` expects a default response.fixAlways ensure that every service method calls the `res` callback at the end of its execution, even if it's `res({})` for an empty response or `res(error)` for an exception. Implement `try-catch` blocks to ensure errors are caught and returned gracefully via `res(error)`. affects: *
Errors
Common errors & fixes
Error: Cannot find module 'express' or Error: Cannot find module 'soap'
`express` or `soap` are peer dependencies and must be installed explicitly in your project, not just implicitly by `express-soap`.
fixRun `npm install express soap` in your project's root directory to install the required peer dependencies.
SOAP Fault: Server Error (or similar generic SOAP fault from client)
This often indicates an unhandled exception occurred within one of your SOAP service methods on the server, or the `res` callback was not correctly invoked, leading to a server-side error that propagates as a generic SOAP fault.
fixReview the server logs for uncaught exceptions within your SOAP service methods. Ensure all service methods handle potential errors gracefully and call the `res` callback with an error object or a valid response under all circumstances.
TypeError: Cannot read properties of undefined (reading 'MyOperation')
The `services` object passed to `express-soap` does not accurately map to the structure (Service Name -> Port Name -> Operation Name) defined in your WSDL, or the WSDL itself is malformed/inaccessible.
fixVerify that your `services` object precisely mirrors the structure of your WSDL, paying close attention to case sensitivity and hierarchy (e.g., `services: { ServiceName: { PortName: { MyOperation: ... } } }`). Double-check the WSDL for correctness and accessibility. Audit
Dependencies
expressrequiredRequired as the host web framework for the middleware. `express-soap` is built specifically for Express applications.
soaprequiredThe core SOAP client and server library that `express-soap` builds upon and wraps. All SOAP logic is handled by `node-soap`.