superapi

0.23.1 verified Fri May 01 auth: no javascript maintenance

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.

Common errors

error TypeError: Cannot read properties of undefined (reading 'get') ↓

cause api.agent is not set; HTTP verb helpers (api.get, api.post) are undefined.

fix

Add api.agent = require('superagent'); after creating the api instance.

error UnhandledPromiseRejectionWarning: TypeError: api.api.getUsers is not a function ↓

cause Service name in config does not match the call; spaces or case mismatch.

fix

Check the services configuration: the key used in api.api[key] must exactly match the key in the services object.

error Error: cannot resolve path: /users ↓

cause Service path is missing leading '/' or baseUrl is misconfigured.

fix

Ensure the path in service config starts with '/' and the baseUrl ends without a slash, or adjust accordingly.

Warnings

gotcha Must assign `superagent` to `api.agent` after creating the instance; forgetting this will cause 'agent is undefined' errors. ↓

fix api.agent = require('superagent');

breaking Direct use of api.get(), api.post(), etc. requires `api.agent` assignment; without it, those methods will throw. ↓

fix Check that api.agent is set before calling HTTP verb helpers.

gotcha Service path must start with '/' unless it is a relative path from baseUrl; misuse may result in incorrect URLs. ↓

fix Ensure service paths are absolute (with leading '/') or correctly relative.

deprecated The library uses an outdated build system and doesn't support ESM natively; importing with ES syntax may fail in bundlers. ↓

fix Use CommonJS require() and ensure a bundler that can handle ES module transpiled code.

gotcha The `superapi.default` export is the main function; in CommonJS, `require('superapi')` returns it directly, not an object with `default` property. ↓

fix Use `const superapi = require('superapi');` instead of `require('superapi').default`.

Install

npm install superapi

yarn add superapi

pnpm add superapi

Imports

default
wrong
```
const superapi = require('superapi')
```
correct
```
import superapi from 'superapi'
```
The module exports a `default` function; in CommonJS, require returns the default function, but the correct import is the default export.
Superapi
```
import superapi from 'superapi'
```
There is no named export; only default export.
api agent injection
wrong
```
const api = require('superapi').default({...}); api.agent = require('superagent');
```
correct
```
const api = superapi({...}); api.agent = require('superagent');
```
When using CommonJS, require('superapi') returns the default function directly, so calling `.default` is unnecessary and will break.

Quickstart

Shows how to configure superapi with a base URL, headers, services, inject superagent, and make GET and POST calls using promises.

import superapi from 'superapi';
import superagent from 'superagent';

const api = superapi({
  baseUrl: 'https://api.example.com',
  headers: { 'X-Requested-With': 'XMLHttpRequest' },
  services: {
    getUsers: {
      path: '/users',
      method: 'GET'
    },
    createUser: {
      path: '/users',
      method: 'POST',
      options: { type: 'json' }
    }
  }
});
api.agent = superagent;

// GET request
api.api.getUsers({ params: { page: 1 } })
  .then(response => console.log(response.body))
  .catch(err => console.error(err));

// POST request
api.api.createUser({ data: { name: 'John' } })
  .then(response => console.log('Created'))
  .catch(err => console.error(err));