{"id":27430,"library":"superapi","title":"superapi","description":"A wrapper around superagent that simplifies HTTP API calls by allowing developers to define services declaratively with methods, paths, and default options. The library provides a centralized configuration for base URL, headers, and options, and returns Promise-based functions for each service. Current version 0.23.1 is stable but has minimal release cadence (last update 2018). It differs from bare superagent by removing boilerplate and enabling service definitions, though it requires manual injection of the superagent agent and is not actively maintained. Superseded by modern alternatives like Axios or ky.","status":"maintenance","version":"0.23.1","language":"javascript","source_language":"en","source_url":"https://github.com/stephanebachelier/superapi","tags":["javascript","http","api","superagent","wrapper"],"install":[{"cmd":"npm install superapi","lang":"bash","label":"npm"},{"cmd":"yarn add superapi","lang":"bash","label":"yarn"},{"cmd":"pnpm add superapi","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for HTTP requests; must be injected via `api.agent`","package":"superagent","optional":false}],"imports":[{"note":"The module exports a `default` function; in CommonJS, require returns the default function, but the correct import is the default export.","wrong":"const superapi = require('superapi')","symbol":"default","correct":"import superapi from 'superapi'"},{"note":"There is no named export; only default export.","wrong":"","symbol":"Superapi","correct":"import superapi from 'superapi'"},{"note":"When using CommonJS, require('superapi') returns the default function directly, so calling `.default` is unnecessary and will break.","wrong":"const api = require('superapi').default({...}); api.agent = require('superagent');","symbol":"api agent injection","correct":"const api = superapi({...}); api.agent = require('superagent');"}],"quickstart":{"code":"import superapi from 'superapi';\nimport superagent from 'superagent';\n\nconst api = superapi({\n  baseUrl: 'https://api.example.com',\n  headers: { 'X-Requested-With': 'XMLHttpRequest' },\n  services: {\n    getUsers: {\n      path: '/users',\n      method: 'GET'\n    },\n    createUser: {\n      path: '/users',\n      method: 'POST',\n      options: { type: 'json' }\n    }\n  }\n});\napi.agent = superagent;\n\n// GET request\napi.api.getUsers({ params: { page: 1 } })\n  .then(response => console.log(response.body))\n  .catch(err => console.error(err));\n\n// POST request\napi.api.createUser({ data: { name: 'John' } })\n  .then(response => console.log('Created'))\n  .catch(err => console.error(err));","lang":"javascript","description":"Shows how to configure superapi with a base URL, headers, services, inject superagent, and make GET and POST calls using promises."},"warnings":[{"fix":"api.agent = require('superagent');","message":"Must assign `superagent` to `api.agent` after creating the instance; forgetting this will cause 'agent is undefined' errors.","severity":"gotcha","affected_versions":"all"},{"fix":"Check that api.agent is set before calling HTTP verb helpers.","message":"Direct use of api.get(), api.post(), etc. requires `api.agent` assignment; without it, those methods will throw.","severity":"breaking","affected_versions":"all"},{"fix":"Ensure service paths are absolute (with leading '/') or correctly relative.","message":"Service path must start with '/' unless it is a relative path from baseUrl; misuse may result in incorrect URLs.","severity":"gotcha","affected_versions":"all"},{"fix":"Use CommonJS require() and ensure a bundler that can handle ES module transpiled code.","message":"The library uses an outdated build system and doesn't support ESM natively; importing with ES syntax may fail in bundlers.","severity":"deprecated","affected_versions":"0.x"},{"fix":"Use `const superapi = require('superapi');` instead of `require('superapi').default`.","message":"The `superapi.default` export is the main function; in CommonJS, `require('superapi')` returns it directly, not an object with `default` property.","severity":"gotcha","affected_versions":"0.x"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Add api.agent = require('superagent'); after creating the api instance.","cause":"api.agent is not set; HTTP verb helpers (api.get, api.post) are undefined.","error":"TypeError: Cannot read properties of undefined (reading 'get')"},{"fix":"Check the `services` configuration: the key used in `api.api[key]` must exactly match the key in the services object.","cause":"Service name in config does not match the call; spaces or case mismatch.","error":"UnhandledPromiseRejectionWarning: TypeError: api.api.getUsers is not a function"},{"fix":"Ensure the path in service config starts with '/' and the baseUrl ends without a slash, or adjust accordingly.","cause":"Service path is missing leading '/' or baseUrl is misconfigured.","error":"Error: cannot resolve path: /users"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}