{"id":15827,"library":"smee-client","title":"Smee Client","description":"Smee Client is a JavaScript/TypeScript library that provides a local proxy for webhooks received by the smee.io service, enabling developers to test webhook integrations without deploying their applications to a publicly accessible server. It listens for incoming webhook payloads on a designated smee.io channel and forwards them to a specified local HTTP endpoint. The current stable version is 5.0.0, released in November 2025, which introduced a breaking change making the `start()` method asynchronous. The project maintains an active release cadence, with several minor and patch updates preceding the major version bump, indicating ongoing development and support. A key differentiator for Smee Client is its straightforward integration with the smee.io platform, offering a simple and effective solution for local development and debugging of applications that rely on external webhook events, such as GitHub App development or payment gateway notifications, by tunneling public internet requests directly to a developer's machine.","status":"active","version":"5.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/probot/smee-client","tags":["javascript","typescript"],"install":[{"cmd":"npm install smee-client","lang":"bash","label":"npm"},{"cmd":"yarn add smee-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add smee-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library primarily uses named exports. `require` is not recommended for modern Node.js and TypeScript environments.","wrong":"const SmeeClient = require('smee-client')","symbol":"SmeeClient","correct":"import { SmeeClient } from 'smee-client'"},{"note":"Import types separately for type-checking without bundling.","symbol":"SmeeClient","correct":"import type { SmeeClientOptions } from 'smee-client'"},{"note":"While `Client` is the internal class name, `SmeeClient` is the recommended named export. There is no default export.","wrong":"import SmeeClient from 'smee-client'","symbol":"SmeeClient","correct":"import { Client as SmeeClient } from 'smee-client'"}],"quickstart":{"code":"import { SmeeClient } from 'smee-client';\n\nasync function runSmeeClient() {\n  // Replace with your unique smee.io URL, e.g., from https://smee.io/\n  // It's highly recommended to set this via an environment variable.\n  const smeeUrl = process.env.SMEE_URL || 'https://smee.io/your-unique-channel-id';\n\n  if (smeeUrl === 'https://smee.io/your-unique-channel-id') {\n    console.warn('Warning: Using a placeholder Smee URL. Please set SMEE_URL environment variable or update the code.');\n    console.warn('Get your unique channel URL from https://smee.io/.');\n  }\n\n  const smee = new SmeeClient({\n    source: smeeUrl,\n    target: 'http://localhost:3000/webhook', // Your local development server endpoint\n    logger: console,\n  });\n\n  console.log(`Forwarding webhooks from ${smeeUrl} to http://localhost:3000/webhook`);\n\n  try {\n    // Client#start() is now an async function since v5.0.0\n    const events = await smee.start();\n    console.log('Smee client started. Waiting for events...');\n\n    events.on('message', (message) => {\n      console.log('Received webhook message:', message.url);\n      // message contains 'headers', 'body', 'url', 'query', etc.\n    });\n\n    events.on('error', (error) => {\n      console.error('Smee client encountered an error:', error);\n    });\n\n    events.on('close', () => {\n      console.log('Smee client connection closed.');\n    });\n\n    // Example: Stop the client after a minute (optional)\n    // setTimeout(() => {\n    //   events.close();\n    //   console.log('Smee client stopped after 1 minute.');\n    // }, 60 * 1000);\n\n  } catch (error) {\n    console.error('Failed to start Smee client:', error);\n  }\n}\n\nrunSmeeClient();","lang":"typescript","description":"This quickstart initializes a SmeeClient to forward webhooks from a smee.io channel to a local endpoint, demonstrating its asynchronous start method and event listening."},"warnings":[{"fix":"Ensure that calls to `smee.start()` are prefixed with `await`. For example: `await smee.start();`","message":"The `Client#start()` method is now an asynchronous function and must be awaited. Previously, it was synchronous.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Refer to the specific version's changelog or documentation to confirm feature availability. If a desired feature was reverted, consider upgrading to v5.x if it has been re-implemented or find an alternative approach.","message":"Features such as connection timeout, `startForward`/`stopForward` methods, and the `query-forwarding` option, which were introduced in versions like `v4.2.0` and `v4.4.0`, were subsequently reverted in `v4.4.2`. Users upgrading from `v4.2.0` or `v4.4.0` might find these functionalities unexpectedly removed in later `v4.x` releases.","severity":"gotcha","affected_versions":">=4.4.2 <5.0.0 (reverted features)"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Change the calling code to `await smee.start();`. Ensure the surrounding function is `async`.","cause":"Attempting to call `smee.start()` without `await` in an asynchronous context after v5.0.0.","error":"TypeError: smee.start is not a function"},{"fix":"Verify that the `source` property is a complete and valid Smee.io channel URL, including the protocol and a unique path. Obtain a fresh URL from https://smee.io/ if unsure.","cause":"The `source` option provided to `new SmeeClient()` is either missing, an empty string, or not a valid `https://smee.io/your-channel` format.","error":"Error: Missing URL / Error: Invalid Smee URL"}],"ecosystem":"npm"}