Express Report-To Middleware

1.1.0 verified Thu Apr 23 auth: no javascript maintenance

This package provides Express.js middleware for setting the HTTP `Report-To` response header, crucial for client-side error reporting via browser APIs. Currently at version 1.1.0, it appears to be in a maintenance phase with no major updates since 2021. Its primary function is to configure reporting endpoints for various browser features, such as `Content-Security-Policy` (CSP) violation reports, Network Error Logging (NEL), or Intervention Reports. A key differentiator is its focus solely on configuring the `Report-To` header, rather than implementing the reporting mechanisms themselves. This design choice means it requires integration with other modules (e.g., `network-error-logging` for NEL) to make the reporting functional. The module offers a structured way to define report groups, `max_age`, `include_subdomains`, and multiple prioritized endpoints, adhering to the W3C Reporting API specification.

Common errors

error TypeError: reportTo is not a function ↓

cause Attempting to use `reportTo` as a named import or without invoking it as a function when requiring it in CommonJS.

fix

For ESM: import reportTo from 'report-to';. For CommonJS: const reportTo = require('report-to');.

error HTTP Header 'Report-To' is missing or invalid in browser developer tools ↓

cause The `report-to` middleware was not applied to the Express app, or the configuration object passed to it was invalid or missing the `groups` array.

fix

Ensure app.use(reportTo({...})); is called before sending responses, and verify that the groups array in the configuration is correctly structured with group, max_age, and endpoints properties.

Warnings

gotcha The `Report-To` header configured by this middleware only defines reporting endpoints. For actual client-side error reporting to occur (e.g., CSP violations, Network Error Logging), you must also set other HTTP response headers (like `Content-Security-Policy-Report-Only` or `NEL`) that reference the defined `Report-To` groups. ↓

fix Ensure that additional reporting headers (e.g., `Content-Security-Policy` with `report-to`, `NEL`) are also set in your application, referencing the `group` names defined in your `report-to` middleware configuration.

gotcha The `max_age` property in your `Report-To` configuration should be sufficiently long to allow browsers to cache the reporting endpoint configuration. Short `max_age` values can lead to unreliable reporting, as browsers might drop the configuration too quickly. ↓

fix Set a `max_age` value in your `Report-To` group configuration that is appropriate for your application's reporting needs, typically several days or weeks (e.g., 2592000 for 30 days) to ensure consistent reporting even across multiple user sessions.

Install

npm install report-to

yarn add report-to

pnpm add report-to

Imports

reportTo
wrong
```
import { reportTo } from 'report-to';
```
correct
```
import reportTo from 'report-to';
```
The primary export is a default function. While the package supports TypeScript, ESM usage should use a default import.

reportTo

wrong

const { reportTo } = require('report-to');

correct

const reportTo = require('report-to');

CommonJS environments use `require` to import the default function.

ReportToOptions
```
import type { ReportToOptions } from 'report-to';
```
TypeScript users can import the `ReportToOptions` interface for type-checking the configuration object.

Quickstart

This quickstart demonstrates how to integrate `report-to` middleware into an Express application, defining a reporting group. It also includes an example of how a complementary `NEL` header would be set, referencing the defined reporting endpoint, as the `Report-To` header alone does not trigger reports.

import express from 'express';
import reportTo from 'report-to';

const app = express();

app.use(reportTo({
    groups: [
		{
			group: "endpoint-1",
			max_age: 10886400,
			include_subdomains: true,
			endpoints: [
				{
					url: "https://example.com/reports",
					priority: 1
				},
				{
					url: "https://backup.com/reports",
					priority: 2
				}
			]
		}
	]
}));

// Example of also setting NEL header, which uses the 'endpoint-1' group defined above
app.use((req, res, next) => {
  res.setHeader('NEL', '{"report_to":"endpoint-1","max_age":31536000,"include_subdomains":true}');
  next();
});

app.get('/', (req, res) => {
  res.send('Hello with Report-To and NEL headers!');
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});