How to upgrade from v1 to v2
This guide will help you navigate through changes included in version 2 of the Node.js integration for a successful upgrade.
Version 2 brings new module packages that are adapted to the environment where DataDome will run.
Documentation for version 2
Please refer to the new documentation for detailed instructions on how to use version 2 of the module.
Overview of the changes
- Deprecation of the
@datadome/node-module
package - Introduction of two new packages:
@datadome/module-express
for usage with the Express framework@datadome/module-http
for usage with the built-in HTTP module from Node.js
- Renaming and deprecation of some options
- Migration to TypeScript
- Support of Node.js upgraded to version 18 and higher
Migration steps
Step 1: Uninstall @datadome/node-module
@datadome/node-module
Remove the v1 package from your project:
npm uninstall @datadome/node-module
Step 2: Install the new package
You need to install only one package, depending on your usage:
If you use the Express framework
Install the @datadome/module-express
package on your project:
npm install @datadome/module-express
If you use the built-in HTTP module
Install the @datadome/module-http
package on your project:
npm install @datadome/module-http
Step 3: Update your integration
If you use the Express framework
- Update the import statement
const { DataDomeExpress } = require('@datadome/module-express');
const DataDome = require('@datadome/node-module');
- Update the parameters to instantiate the
DatadomeExpress
class
const datadomeClient = new DatadomeExpress('Some key');
const datadomeClient = new DataDome('Some Key', 'api.datadome.co');
- Use the
middleware
method to protect your Express application
const app = express();
app.use(datadomeClient.middleware());
const app = express();
app.use(function (req, resp, next) {
datadomeClient.authCallback(
req,
resp,
function () {
console.log('Passed');
next();
},
function () {
console.log('Rejected');
}
);
});
This implementation provides a basic setup for typical use cases.
For more advanced configurations, please refer to the new documentation.
You are now using the new Express integration!
If you use the built-in HTTP module
- Update the import statement
const { DataDomeHttp } = require('@datadome/module-http');
const DataDome = require('@datadome/node-module');
- Update the parameters to instantiate the
DatadomeHttp
class and remove the handlers for theblocked
andvalid
events
Note: The handlers will be re-implemented on the next step in the request listener ofhttp.createServer
const datadomeClient = new DatadomeHttp('Some key');
const datadomeClient = new DataDome('Some Key', 'api.datadome.co')
.on('blocked', function(req) {
console.log('DataDome blocked this request');
})
.on('valid', function(req, res) {
console.log('DataDome passed this request');
res.statusCode = 200;
res.setHeader('Content-Type', 'text/plain');
res.end('Hello World');
});
- Update the request listener for
http.createServer
:- Make it
async
to allow the use ofawait
- Handle results from the DataDome middleware
- Make it
const server = http.createServer(async (req, res) => {
const { result, error } = await datadomeClient.handleRequest(req, res);
if (result === 'ALLOW') { // This section corresponds to the 'valid' event
console.log('Request allowed');
if (error) {
console.error(error);
}
} else { // This section corresponds to the 'blocked' event
console.log('Request challenged');
}
if (req.url === '/') {
res.statusCode = 200;
res.setHeader('Content-Type', 'text/plain');
res.end('Hello World');
} else {
res.statusCode = 404;
res.setHeader('Content-Type', 'text/plain');
res.end('Not Found');
}
});
const server = http.createServer((req, res) => {
datadomeClient.auth(req, res);
});
You are now using the new HTTP integration!
Step 4: Update your configuration
The constructor of each module accepts an object as its second parameter to customize the behavior of the module.
The table below lists options from v1 and their counterparts for v2:
Option name (v1) | Option name (v2) | Description | Default value |
---|---|---|---|
ssl | REMOVED | Use HTTPS to connect to the Protection API. | true |
port | REMOVED | Port of the Protection API to connect to. | 443 |
path | REMOVED | Path to route payloads on the Protection API. | '/validate-request/' |
timeout | timeout | Timeout in milliseconds, after which the request will be allowed. | 150 |
uriRegex | urlPatternInclusion | Regex to match to process the request with the Protection API. If null , all requests that don't match urlPatternExclusion will be processed. | null |
uriRegexExclusion | urlPatternExclusion | Regex to match to exclude requests from being processed with the Protection API. If null , all requests will be processed. | \.(avi|flv|mka|mkv|mov|mp4|mpeg|mpg|mp3|flac|ogg|ogm|opus|wav|webm|webp|bmp|gif|ico|jpeg|jpg|png|svg|svgz|swf|eot|otf|ttf|woff|woff2|css|less|js|map|json|avif|xml|gz|zip)$ |
- | endpointHost | Host of the Protection API. | 'api.datadome.co' |
Updated about 1 month ago