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.
userAgent
✓ import { userAgent } from 'popsicle-user-agent';
✗ const userAgent = require('popsicle-user-agent').userAgent;
The library primarily uses named ESM exports. While CommonJS `require` works, the TypeScript definitions and modern usage favor ESM.
This quickstart demonstrates how to apply the `userAgent` middleware to a `Popsicle` middleware stack, showing both the default and a custom User-Agent string being set on outgoing requests before they reach a mock transport layer.
import { userAgent } from 'popsicle-user-agent';
import { compose } from 'servie'; // 'servie' is the peer dep and typically provides 'compose'
// Mock transport function for demonstration.
// In a real application, you would typically import a transport like 'popsicle-transport-http'
// and use it with the actual 'popsicle' client.
const mockTransport = () => async (req: Request): Promise<Response> => {
console.log(`[Mock Transport] Sending request to: ${req.url}`);
console.log(`[Mock Transport] User-Agent header: ${req.headers.get('User-Agent')}`);
// Simulate network delay and return a simple response
await new Promise(resolve => setTimeout(resolve, 50));
return new Response('{"message": "Request processed"}', {
status: 200,
headers: { 'Content-Type': 'application/json' }
});
};
async function runExample() {
// 1. Create a middleware stack with the default User-Agent
const defaultStack = compose([
userAgent(), // Defaults to "Popsicle"
mockTransport()
]);
console.log('--- Request with default User-Agent ---');
const defaultRequest = new Request('https://api.example.com/data');
await defaultStack(defaultRequest);
// 2. Create a middleware stack with a custom User-Agent
const customStack = compose([
userAgent('MyAwesomeApp/1.2.3 (Node.js)'),
mockTransport()
]);
console.log('\n--- Request with custom User-Agent ---');
const customRequest = new Request('https://api.example.com/status');
await customStack(customRequest);
// To integrate with an actual popsicle client (conceptual):
// import * as popsicle from 'popsicle';
// const client = popsicle.create({ baseUrl: 'https://api.example.com' }).use(customStack);
// const response = await client.get('/some-path');
// console.log('Actual Popsicle Client Response Status:', response.status);
}
runExample().catch(console.error);
Debug
Known issues
breakingThe `User-Agent` header setting functionality was extracted from the core `popsicle` library into this dedicated `popsicle-user-agent` package. Users upgrading `popsicle` who previously relied on this built-in behavior will find it missing.fixInstall `popsicle-user-agent` (`npm install popsicle-user-agent`) and explicitly add `userAgent()` to your `popsicle` middleware composition chain.
affects: >=1.0.0 (for this package); Affects users migrating from older `popsicle` versions.
Errors
Common errors & fixes
Cannot find module 'servie' or its corresponding type declarations.
`servie` is a peer dependency of `popsicle-user-agent` and is required for the middleware composition (e.g., the `compose` function), but it has not been installed in your project.
fixInstall the `servie` package: `npm install servie`.
TypeError: (0 , servie_1.compose) is not a function
This typically occurs in a CommonJS environment or when bundlers struggle with ESM exports if `servie` is imported incorrectly. The `compose` function is a named export from `servie`.
fixEnsure `servie` is imported correctly as `import { compose } from 'servie';` for ESM, or `const { compose } = require('servie');` for CommonJS, and that your build setup supports these imports. Audit
Dependencies
servierequiredPeer dependency required for middleware composition, as Popsicle's architecture relies on Servie's request processing primitives.