{"id":11062,"library":"hud-sdk","title":"Hud Node.js SDK","description":"The `hud-sdk` package provides a lightweight, low-overhead runtime sensor for Node.js applications, designed to capture real-time, function-level behavior directly from production environments. It observes performance characteristics, error behavior, and execution patterns without requiring manual instrumentation, logs, or dashboards. The SDK integrates with various developer tools, including IDEs and CI/CD pipelines, and is specifically optimized for AI-assisted development workflows (e.g., GitHub Copilot, Cursor) to ensure AI-generated code is production-safe. Current stable version is 1.8.3, with frequent updates indicated by its last publish date. It differentiates itself by offering continuous visibility directly in the developer's IDE, focusing on high-fidelity, function-level data, and adhering to strict security and privacy standards (SOC 2 Type II, ISO 27001, GDPR compliance), transmitting only anonymized metadata.","status":"active","version":"1.8.3","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","sdk","developer-tool","runtime-analysis","code-behavior","api-integration","cloud","automation","observability","typescript"],"install":[{"cmd":"npm install hud-sdk","lang":"bash","label":"npm"},{"cmd":"yarn add hud-sdk","lang":"bash","label":"yarn"},{"cmd":"pnpm add hud-sdk","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The `register` function is the primary entry point to initialize the Hud SDK. It should be called as early as possible in your application's entry point for optimal auto-instrumentation. Ensure your `package.json` specifies `\"type\": \"module\"` for ESM, or use CommonJS `require()` if not.","wrong":"const Hud = require('hud-sdk'); Hud.register(...);","symbol":"register","correct":"import { register } from 'hud-sdk';"},{"note":"While auto-instrumentation is the primary use case, advanced scenarios might require interacting with a client. This is a common pattern, though specific direct client interaction is less emphasized for general setup. Always refer to official documentation for advanced usage.","symbol":"HudClient","correct":"import { HudClient } from 'hud-sdk/client';"},{"note":"The SDK likely exposes multiple named exports, making `import * as Hud` suitable for accessing various utilities or the `register` function (e.g., `Hud.register()`) if not directly destructuring. Avoid a default import unless explicitly documented, as it's less common for libraries with multiple exports.","wrong":"import Hud from 'hud-sdk';","symbol":"* as Hud","correct":"import * as Hud from 'hud-sdk';"}],"quickstart":{"code":"import { register } from 'hud-sdk';\n\n// Ensure this is called as early as possible in your application's entry file.\n// It's crucial for Hud's auto-instrumentation to wrap functions correctly.\nregister({\n  apiKey: process.env.HUD_API_KEY ?? '',\n  // Optional: Provide a service name for better identification in Hud's dashboard\n  serviceName: process.env.SERVICE_NAME ?? 'my-nodejs-app',\n  // Optional: Enable debug logging if needed for troubleshooting\n  // debug: process.env.NODE_ENV === 'development'\n});\n\n// Example of a simple Express app to demonstrate instrumentation\nimport express from 'express';\n\nconst app = express();\nconst port = 3000;\n\napp.get('/', (req, res) => {\n  console.log('Request received for /');\n  res.send('Hello from Hud-instrumented app!');\n});\n\napp.get('/error', (req, res) => {\n  console.error('Simulating an error!');\n  throw new Error('This is a simulated error detected by Hud!');\n});\n\napp.listen(port, () => {\n  console.log(`Server running on http://localhost:${port}`);\n});\n","lang":"typescript","description":"This quickstart initializes the Hud Node.js SDK for runtime monitoring and demonstrates a basic Express application whose routes and errors will be automatically instrumented and monitored by Hud. It requires a `HUD_API_KEY` environment variable."},"warnings":[{"fix":"Ensure `import { register } from 'hud-sdk';` and its subsequent `register()` call are the very first executable lines in your application's main entry file (e.g., `src/index.ts` or `app.js`).","message":"The `register()` call must be placed as early as possible in your application's entry file, typically before any other application code or framework imports. Delaying this call can result in incomplete or incorrect instrumentation, as Hud might miss wrapping certain functions or modules.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Refer to the official Hud documentation for the compatibility matrix and upgrade your Node.js runtime to a supported version. Restart your service after the update.","message":"Running the SDK with an unsupported Node.js version will prevent it from loading and initiating graceful shutdown. This means no runtime data will be collected.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Verify network connectivity to `https://api-prod.hud.io`, check proxy/firewall settings, and ensure any custom CA certificates are correctly configured in your Node.js environment (e.g., via `NODE_EXTRA_CA_CERTS`).","message":"Failure to communicate with the Hud backend due to network issues, firewall restrictions, proxy configurations, or untrusted certificates will cause the SDK to shut down gracefully.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Run `ts-node` with `--transpileOnly` flag (e.g., `npx ts-node --transpileOnly index.ts`), set `TS_NODE_TRANSPILE_ONLY=true` environment variable, or configure it programmatically. Also, ensure `ts-node` is installed locally in your project dependencies (`npm install ts-node`).","message":"When using `ts-node` for TypeScript execution, Hud requires it to run in `transpileOnly` mode to avoid performance issues and ensure proper module loading. If `ts-node` is not resolvable locally, Hud will also gracefully shut down.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If this occurs, consider reducing the number of instrumented functions by excluding certain modules if your application is exceptionally large or complex. Consult Hud support for guidance on configuring instrumentation scope.","message":"The SDK has an internal limit on the number of functions it can instrument to prevent performance degradation. Exceeding this limit will cause the SDK to gracefully shut down.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Check the Hud SDK's compatibility matrix and upgrade your Node.js runtime to a supported version, then restart your service.","cause":"The application is running a Node.js version not supported by the Hud SDK.","error":"Hud: Can't load Hud due to an unsupported Node.js version."},{"fix":"Verify outbound network connectivity from your runtime host to `https://api-prod.hud.io`. Check firewall, proxy settings, and ensure custom SSL certificates are trusted by Node.js.","cause":"The SDK failed to establish or maintain communication with the Hud backend after multiple retry attempts.","error":"Hud: SDK has initiated a graceful shutdown. Your application remains unaffected. (Error E9002)"},{"fix":"Reduce the scope of instrumentation, potentially by configuring the SDK to exclude specific modules or paths. Consult Hud documentation or support for configuration options to manage instrumentation.","cause":"Your application has too many functions, exceeding the SDK's internal instrumentation limit.","error":"Hud: SDK limit of instrumented functions exceeded. SDK has initiated a graceful shutdown. Your application remains unaffected. (Error E1022)"},{"fix":"Ensure `register()` is called at the very beginning of your application. Invoke your HTTP endpoints to generate traffic. Check Hud's support matrix for your specific HTTP framework.","cause":"Hud's SDK did not detect or collect data for your HTTP endpoints, possibly due to `register()` being called too late, unsupported framework, or endpoints not being invoked.","error":"I don't see any endpoints in Hud dashboard."},{"fix":"Install `ts-node` locally in your project (`npm install ts-node`). Ensure `npx ts-node` or `node --require ts-node/register` is used to run your TypeScript application, rather than a globally installed `ts-node` or other problematic setups.","cause":"`ts-node` is either not installed locally or not resolvable by Hud's module loading mechanism.","error":"Hud: 'ts-node' was detected but could not be resolved by Hud. This may happen if 'ts-node' is installed globally. Try installing it locally in your project. The SDK has initiated a graceful shutdown."}],"ecosystem":"npm"}