{"id":17459,"library":"popsicle-user-agent","title":"Popsicle User Agent Middleware","description":"popsicle-user-agent is a specialized middleware designed for the Popsicle HTTP client library, facilitating the automatic setting of a `User-Agent` header for outgoing requests. Its current stable version is 1.0.0, an initial release that extracts this functionality from the Popsicle core. This signifies a modular approach to Popsicle's feature set, where specific concerns like user agent management are handled by dedicated packages. This package provides a simple, composable function, `userAgent()`, that can be seamlessly integrated into Popsicle's middleware chain. This allows developers to easily standardize the `User-Agent` string for all requests made through a specific Popsicle instance or a composed middleware stack. The primary differentiator is its tight integration within the Popsicle ecosystem, offering a lightweight and focused solution without introducing external dependencies beyond Popsicle itself and its peer dependency, Servie. Given its highly specific utility, the package is expected to maintain a stable API with infrequent, targeted releases, focusing on reliability rather than rapid feature expansion.","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":"git://github.com/serviejs/popsicle-user-agent","tags":["javascript","popsicle","cookies","jar","memory","store","typescript"],"install":[{"cmd":"npm install popsicle-user-agent","lang":"bash","label":"npm"},{"cmd":"yarn add popsicle-user-agent","lang":"bash","label":"yarn"},{"cmd":"pnpm add popsicle-user-agent","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for middleware composition, as Popsicle's architecture relies on Servie's request processing primitives.","package":"servie","optional":false}],"imports":[{"note":"The library primarily uses named ESM exports. While CommonJS `require` works, the TypeScript definitions and modern usage favor ESM.","wrong":"const userAgent = require('popsicle-user-agent').userAgent;","symbol":"userAgent","correct":"import { userAgent } from 'popsicle-user-agent';"}],"quickstart":{"code":"import { userAgent } from 'popsicle-user-agent';\nimport { compose } from 'servie'; // 'servie' is the peer dep and typically provides 'compose'\n\n// Mock transport function for demonstration.\n// In a real application, you would typically import a transport like 'popsicle-transport-http'\n// and use it with the actual 'popsicle' client.\nconst mockTransport = () => async (req: Request): Promise<Response> => {\n  console.log(`[Mock Transport] Sending request to: ${req.url}`);\n  console.log(`[Mock Transport] User-Agent header: ${req.headers.get('User-Agent')}`);\n  // Simulate network delay and return a simple response\n  await new Promise(resolve => setTimeout(resolve, 50));\n  return new Response('{\"message\": \"Request processed\"}', {\n    status: 200,\n    headers: { 'Content-Type': 'application/json' }\n  });\n};\n\nasync function runExample() {\n  // 1. Create a middleware stack with the default User-Agent\n  const defaultStack = compose([\n    userAgent(), // Defaults to \"Popsicle\"\n    mockTransport()\n  ]);\n\n  console.log('--- Request with default User-Agent ---');\n  const defaultRequest = new Request('https://api.example.com/data');\n  await defaultStack(defaultRequest);\n\n  // 2. Create a middleware stack with a custom User-Agent\n  const customStack = compose([\n    userAgent('MyAwesomeApp/1.2.3 (Node.js)'),\n    mockTransport()\n  ]);\n\n  console.log('\\n--- Request with custom User-Agent ---');\n  const customRequest = new Request('https://api.example.com/status');\n  await customStack(customRequest);\n\n  // To integrate with an actual popsicle client (conceptual):\n  // import * as popsicle from 'popsicle';\n  // const client = popsicle.create({ baseUrl: 'https://api.example.com' }).use(customStack);\n  // const response = await client.get('/some-path');\n  // console.log('Actual Popsicle Client Response Status:', response.status);\n}\n\nrunExample().catch(console.error);\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Install `popsicle-user-agent` (`npm install popsicle-user-agent`) and explicitly add `userAgent()` to your `popsicle` middleware composition chain.","message":"The `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.","severity":"breaking","affected_versions":">=1.0.0 (for this package); Affects users migrating from older `popsicle` versions."}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Install the `servie` package: `npm install servie`.","cause":"`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.","error":"Cannot find module 'servie' or its corresponding type declarations."},{"fix":"Ensure `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.","cause":"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`.","error":"TypeError: (0 , servie_1.compose) is not a function"}],"ecosystem":"npm","meta_description":null}