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.
Metrics
✓ import { Metrics } from 'readmeio';
✗ const Metrics = require('readmeio');
The `Metrics` class is the primary entry point for manual API logging. While CommonJS `require` might work in some environments due to Node.js 14+ compatibility layers, ESM `import` is the recommended and more modern approach, especially in TypeScript projects.
expressMiddleware
✓ import { expressMiddleware } from 'readmeio';
✗ const expressMiddleware = require('readmeio').expressMiddleware;
This named export provides a convenient middleware function for Express.js applications. Prefer destructuring for named exports. Direct property access on `require()` is a CommonJS pattern.
MetricsOptions
✓ import type { MetricsOptions } from 'readmeio';
✗ import { MetricsOptions } from 'readmeio';
For type definitions in TypeScript, use `import type` to ensure they are removed during compilation, preventing potential runtime issues and ensuring proper tree-shaking.
Demonstrates how to initialize the ReadMe Metrics SDK, create a basic HTTP server, and log simulated API requests and responses, including data redaction for sensitive fields, to the ReadMe.com dashboard. Includes graceful shutdown.
import { Metrics } from 'readmeio';
import http from 'http';
// Initialize the ReadMe Metrics SDK
// In a real application, retrieve process.env.README_API_KEY and process.env.NODE_ENV securely
const metrics = new Metrics({
apiKey: process.env.README_API_KEY ?? 'your_readme_api_key_here',
development: process.env.NODE_ENV !== 'production',
});
// Create a simple HTTP server to simulate API calls
const server = http.createServer(async (req, res) => {
// Simulate an incoming request
const requestBody = { user: 'testuser', data: 'some data', sensitive_id: '12345' };
const requestHeaders = {
'content-type': 'application/json',
'x-api-key': 'super-secret-internal-key', // Example of a header that might be redacted
'user-agent': 'node-http-client',
};
// Simulate an outgoing response
const responseBody = { status: 'success', message: 'Hello from API', internal_ref: 'xyz' };
const responseHeaders = {
'content-type': 'application/json',
'x-response-id': 'uuid-12345',
};
// Log the request and response to ReadMe
try {
await metrics.log({
// Full URL is important for ReadMe metrics to categorize endpoints
url: new URL(`http://localhost:3000${req.url}`),
method: req.method ?? 'GET',
api: {
key: 'user-id-123', // Identifier for the user making the API call
// label: 'Optional label for this user/API key'
},
// Redaction example: prevent 'x-api-key' header from being sent to ReadMe
// and prevent 'user' field in request body
redact: {
headers: ['x-api-key'],
body: ['user', 'sensitive_id'],
},
request: {
headers: requestHeaders,
body: JSON.stringify(requestBody),
},
response: {
status: 200,
headers: responseHeaders,
body: JSON.stringify(responseBody),
},
});
} catch (error) {
console.error('Failed to log metrics:', error);
}
res.writeHead(200, { 'Content-Type': 'application/json' });
res.end(JSON.stringify(responseBody));
});
server.listen(3000, () => {
console.log('Server running on http://localhost:3000');
console.log('Send a request, e.g., curl http://localhost:3000/api/test');
console.log('Check your ReadMe.com dashboard for metrics.');
});
// Example of how to shut down cleanly
process.on('SIGINT', () => {
console.log('Shutting down server...');
server.close(async () => {
// Ensure any buffered logs are sent before exiting
try {
await metrics.sendQueue();
console.log('Buffered logs sent.');
} catch (error) {
console.error('Failed to send remaining logs:', error);
}
console.log('Server gracefully shut down.');
process.exit(0);
});
});
Errors
Common errors & fixes
Error: You must provide an API key. Please visit https://dash.readme.com/project/YOUR_PROJECT/v1.0/api-metrics to get one.
The `apiKey` option was not provided or was empty during the `Metrics` class instantiation.
fixEnsure `apiKey` is passed to the `Metrics` constructor, typically from an environment variable (e.g., `new Metrics({ apiKey: process.env.README_API_KEY })`). TypeError: (0 , readmeio__WEBPACK_IMPORTED_MODULE_0__.Metrics) is not a constructor
This error often occurs in bundled environments (like Webpack or Vite) when mixing CommonJS `require` semantics with ESM `import` syntax, or incorrectly trying to import a named export as a default export.
fixEnsure you are using `import { Metrics } from 'readmeio';` for named imports. Verify your bundler configuration correctly handles ESM and CJS interop, especially if your project is `type: 'module'`. TypeError: metrics.log is not a function
The `metrics` object was not correctly instantiated, or `log` was called before the object was fully initialized.
fixDouble-check that `new Metrics({ ... })` was successfully called and that the resulting instance is available when `log` is invoked. Ensure there are no asynchronous initialization issues preventing `metrics` from being assigned. ERR_REQUIRE_ESM
Attempting to use `require('readmeio')` in a pure ESM context (e.g., in a Node.js project with `"type": "module"` in `package.json` where `readmeio` might not provide a CommonJS entry point for that specific environment).
fixMigrate your import statements from `const { Metrics } = require('readmeio');` to `import { Metrics } from 'readmeio';`. Ensure your project and build tools are configured to handle ESM. Audit
Dependencies
No dependency data recorded yet.