{"id":17733,"library":"kinetex","title":"Kinetex Universal HTTP Client","description":"Kinetex is an early-stage universal HTTP client designed for a wide range of JavaScript runtimes, including Node.js (v18+), browsers, Deno, Bun, and Cloudflare Workers. Currently at version `0.0.2`, it aims to provide a comprehensive solution with built-in support for advanced features such as HTTP/2 and HTTP/3, schema validation (via Zod or Valibot), a flexible middleware system, and integrated utilities for caching, request deduplication, retries, HAR recording, Server-Sent Events (SSE), and GraphQL. Its key differentiators include its broad runtime compatibility, modern HTTP protocol support, and extensive feature set that often requires multiple separate libraries in other HTTP clients. The project is in active, rapid development, and API stability cannot be guaranteed at this early stage.","status":"active","version":"0.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/kinetexjs/kinetex","tags":["javascript","http","https","fetch","request","client","universal","http2","http3","typescript"],"install":[{"cmd":"npm install kinetex","lang":"bash","label":"npm"},{"cmd":"yarn add kinetex","lang":"bash","label":"yarn"},{"cmd":"pnpm add kinetex","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for schema validation.","package":"zod","optional":true},{"reason":"Peer dependency for high-performance HTTP/1.1 and HTTP/2 client in Node.js environments.","package":"undici","optional":true},{"reason":"Peer dependency for an alternative, lightweight schema validation library.","package":"valibot","optional":true},{"reason":"Peer dependency for SOCKS proxy support.","package":"socks-proxy-agent","optional":true}],"imports":[{"note":"The default export is a pre-configured instance of the Kinetex client, ready for immediate use. Kinetex is ESM-only; CommonJS `require()` is not supported.","wrong":"import { kinetex } from 'kinetex';\nconst kinetex = require('kinetex');","symbol":"kinetex","correct":"import kinetex from 'kinetex';"},{"note":"Use the named export `Kinetex` to instantiate a custom client with specific configurations (e.g., custom base URL, middleware). Kinetex is ESM-only.","wrong":"import Kinetex from 'kinetex';\nconst { Kinetex } = require('kinetex');","symbol":"Kinetex","correct":"import { Kinetex } from 'kinetex';"},{"note":"Helper function for defining type-safe middleware. This ensures correct type inference and adherence to the middleware interface. Kinetex is ESM-only.","wrong":"import defineMiddleware from 'kinetex';\nconst { defineMiddleware } = require('kinetex');","symbol":"defineMiddleware","correct":"import { defineMiddleware } from 'kinetex';"}],"quickstart":{"code":"import kinetex, { defineMiddleware } from 'kinetex';\nimport { z } from 'zod'; // Assuming Zod is installed: npm install zod\n\nconst authMiddleware = defineMiddleware(async (ctx, next) => {\n  console.log(`Requesting: ${ctx.url}`);\n  ctx.request.headers.set('Authorization', `Bearer ${process.env.API_TOKEN ?? 'your-secret-token'}`);\n  const response = await next(ctx);\n  console.log(`Response status: ${response.status}`);\n  return response;\n});\n\nconst userSchema = z.object({\n  id: z.number(),\n  name: z.string(),\n  email: z.string().email(),\n});\n\nasync function fetchUserData() {\n  try {\n    const response = await kinetex\n      .use(authMiddleware)\n      .get('https://jsonplaceholder.typicode.com/users/1')\n      .response(userSchema);\n\n    console.log('Fetched User Data:', response.data);\n  } catch (error) {\n    if (error instanceof z.ZodError) {\n      console.error('Validation Error:', error.errors);\n    } else {\n      console.error('Fetch Error:', error.message);\n    }\n  }\n}\n\nfetchUserData();","lang":"typescript","description":"Demonstrates importing the default `kinetex` instance, defining a custom middleware, and performing a GET request with Zod schema validation for the response body. It also includes basic error handling for validation and network issues."},"warnings":[{"fix":"Review the changelog and GitHub issues for each update. Pin exact versions for production use and dedicate time for migration when updating.","message":"Kinetex is currently in a very early development stage (v0.0.2). Expect frequent and potentially breaking API changes between minor and even patch versions as the project stabilizes. Avoid using in production without thorough testing and readiness for rapid updates.","severity":"breaking","affected_versions":">=0.0.1"},{"fix":"Install required peer dependencies alongside Kinetex: `npm install kinetex zod undici valibot socks-proxy-agent` (install only those relevant to your use case).","message":"Kinetex relies on specific peer dependencies for core functionality like schema validation (Zod, Valibot) and Node.js HTTP client (Undici). These must be installed manually by the user, as Kinetex does not bundle them. Failure to install them will result in runtime errors.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Ensure your project runs on Node.js 18+ and is configured as an ESM module (e.g., by adding `\"type\": \"module\"` to your `package.json` or using `.mjs` file extensions).","message":"Kinetex targets modern JavaScript environments and explicitly requires Node.js version 18 or higher. It is an ESM-only package and does not support CommonJS `require()` syntax. Attempting to use it in older Node.js versions or CommonJS modules will lead to import errors.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Install Zod as a direct dependency: `npm install zod`.","cause":"The `zod` peer dependency is not installed, but Kinetex attempts to use it for schema validation.","error":"Error: Cannot find module 'zod' or its corresponding type declarations."},{"fix":"Configure your project for ESM by adding `\"type\": \"module\"` to your `package.json`, ensure your Node.js version is >=18, and use `import` statements.","cause":"Attempting to import Kinetex, an ESM-only package, using CommonJS `require()` in a non-ESM context.","error":"ERR_REQUIRE_ESM: require() of ES Module .../node_modules/kinetex/dist/index.js from ... not supported."},{"fix":"Ensure you correctly import the default Kinetex instance: `import kinetex from 'kinetex';`","cause":"Incorrect import of the default Kinetex client instance. Forgetting `import kinetex from 'kinetex';` and trying to use `kinetex` as if it were globally available, or importing it incorrectly as a named export (`import { kinetex } from 'kinetex';`) where `kinetex` itself is the default export.","error":"TypeError: Cannot read properties of undefined (reading 'get')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}