Superagent HTTP: Ajax for Node and Browser

Hook

I still remember the day I spent six hours debugging a failed API request in production. The error message was cryptic, the request body wasn't being sent correctly, and I had no idea what headers were actually hitting the server. I was using the native fetch API, and while it's powerful, it felt like I was fighting against it rather than working with it. The boilerplate code was everywhere—JSON parsing, error handling, header management—it was a mess. That's when a senior developer on my team introduced me to Superagent. Within minutes, I had rewritten my API calls with cleaner, more readable code. The debugging became trivial because Superagent's chainable API made it crystal clear what was happening at each step. That production bug? Fixed in 20 minutes. Sometimes the right tool doesn't just save time—it saves your sanity.

Table of Contents

• What is Superagent HTTP?
• Quick Start
• 5 Essential Patterns
  • Pattern 1: Handling JSON APIs
  • Pattern 2: File Uploads
  • Pattern 3: Request Retry Logic
  • Pattern 4: Authentication Headers
  • Pattern 5: Query Parameters and Timeouts
• Comparison Table
• 3 Common Mistakes
• FAQ
• Conclusion

What is Superagent HTTP?

Superagent is a lightweight, progressive HTTP client library that works seamlessly in both Node.js and browser environments. Created by TJ Holowaychuk (the same mind behind Express.js), Superagent provides an elegant, chainable API for making HTTP requests without the verbosity and complexity of native solutions.

What sets Superagent apart is its philosophy: HTTP requests should be simple and readable. Instead of dealing with callbacks, promise chains, and manual header management, Superagent gives you a fluent interface that reads almost like plain English. You chain methods together—.get(), .send(), .set()—and the library handles the heavy lifting.

The library supports all standard HTTP methods (GET, POST, PUT, DELETE, PATCH), automatic serialization of request data, parsing of response bodies, and built-in retry logic. It's particularly popular in the Node.js ecosystem but works equally well in browsers, making it perfect for isomorphic applications where you need consistent HTTP handling across environments.

With over 16,000 stars on GitHub and millions of weekly downloads on npm, Superagent has proven itself as a reliable choice for developers who value clean, maintainable code. Whether you're building a REST API client, scraping websites, or handling complex file uploads, Superagent provides the tools you need without unnecessary complexity.

Quick Start

Getting started with Superagent is straightforward. First, install it via npm:

npm install superagent

Here's your first request:

const request = require('superagent');

// Simple GET request
request
  .get('https://api.github.com/users/octocat')
  .end((err, res) => {
    if (err) {
      console.error('Request failed:', err);
      return;
    }
    console.log('User data:', res.body);
  });

// Using async/await (cleaner!)
async function getUser() {
  try {
    const res = await request.get('https://api.github.com/users/octocat');
    console.log('User data:', res.body);
  } catch (err) {
    console.error('Request failed:', err);
  }
}

The beauty of Superagent becomes immediately apparent. Notice how res.body automatically contains the parsed JSON? No manual JSON.parse() needed. The library detects the Content-Type header and handles parsing automatically.

The chainable API means you can add headers, query parameters, and request bodies by simply chaining more methods. Each method returns the request object, allowing you to build complex requests in a readable, top-to-bottom fashion. The .end() method executes the request with a callback, but I prefer using async/await for cleaner error handling and more modern code structure.

In the browser, you can use Superagent via a CDN or bundler like Webpack. The API remains identical, which is fantastic for code reusability across your stack.

5 Essential Patterns

Pattern 1: Handling JSON APIs

const request = require('superagent');

async function createUser(userData) {
  const res = await request
    .post('https://api.example.com/users')
    .send(userData)
    .set('Content-Type', 'application/json')
    .set('Accept', 'application/json');

  return res.body;
}

// Usage
const newUser = await createUser({
  name: 'Jane Doe',
  email: 'jane@example.com'
});

Working with JSON APIs is Superagent's bread and butter. The .send() method automatically serializes JavaScript objects to JSON when the content type is appropriate. You don't need to manually stringify your data or parse responses—Superagent handles both directions automatically.

The .set() method adds headers, and you can chain multiple calls for different headers. Superagent is smart enough to set Content-Type: application/json automatically when you send an object, but I like being explicit for clarity. The response object's .body property contains the parsed JSON, while .text gives you the raw response string if needed.

Pattern 2: File Uploads

const request = require('superagent');

async function uploadAvatar(filePath, userId) {
  const res = await request
    .post('https://api.example.com/upload')
    .field('userId', userId)
    .attach('avatar', filePath)
    .on('progress', event => {
      console.log(`Upload progress: ${event.percent}%`);
    });

  return res.body.url;
}

// Browser usage with File object
async function uploadFromBrowser(fileInput) {
  const file = fileInput.files[0];
  const res = await request
    .post('https://api.example.com/upload')
    .attach('avatar', file, file.name);

  return res.body;
}

File uploads are notoriously tricky with native APIs, but Superagent makes them painless. The .attach() method handles multipart form data automatically. You can mix regular form fields with file attachments using .field() and .attach() respectively.

The progress event listener is incredibly useful for showing upload progress to users. In Node.js, you pass file paths; in browsers, you pass File objects from input elements. Superagent abstracts away the differences, giving you a consistent API across environments.

Pattern 3: Request Retry Logic

const request = require('superagent');

async function fetchWithRetry(url) {
  const res = await request
    .get(url)
    .retry(3, (err, res) => {
      // Retry on network errors or 5xx responses
      if (err && err.code === 'ECONNRESET') return true;
      if (res && res.status >= 500) return true;
      return false;
    })
    .timeout({
      response: 5000,  // Wait 5 seconds for server response
      deadline: 60000  // Allow 60 seconds for entire request
    });

  return res.body;
}

Network requests fail. It's not a matter of if, but when. Superagent's built-in retry mechanism is a lifesaver for handling transient failures. The .retry() method accepts a count and an optional callback that determines whether to retry based on the error or response.

This pattern is essential for production applications where you're dealing with unreliable networks or services. The timeout configuration prevents hanging requests—response timeout starts when the connection is established, while deadline limits the entire request lifecycle. This two-tier approach gives you fine-grained control over request timing.

Pattern 4: Authentication Headers

const request = require('superagent');

class APIClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseURL = 'https://api.example.com';
  }

  async get(endpoint) {
    return await request
      .get(`${this.baseURL}${endpoint}`)
      .set('Authorization', `Bearer ${this.apiKey}`)
      .set('User-Agent', 'MyApp/1.0');
  }

  async post(endpoint, data) {
    return await request
      .post(`${this.baseURL}${endpoint}`)
      .set('Authorization', `Bearer ${this.apiKey}`)
      .send(data);
  }
}

// Usage
const client = new APIClient('your-api-key');
const users = await client.get('/users');

Wrapping Superagent in a client class is a pattern I use constantly. It centralizes authentication, base URLs, and common headers. Every request automatically includes your auth token without repetitive code. This pattern also makes it easy to swap authentication methods—just update the class, and all requests benefit.

You can extend this pattern with interceptors for logging, error handling, or request transformation. The class structure also makes testing easier since you can mock the entire client.

Pattern 5: Query Parameters and Timeouts

const request = require('superagent');

async function searchUsers(filters) {
  const res = await request
    .get('https://api.example.com/users')
    .query({
      page: filters.page || 1,
      limit: filters.limit || 20,
      sort: filters.sort || 'created_at'
    })
    .query({ active: true })  // Can chain multiple .query() calls
    .timeout(10000);

  return {
    users: res.body.data,
    total: res.body.total,
    page: res.body.page
  };
}

Query parameters are cleaner with Superagent's .query() method. Pass an object, and it handles URL encoding automatically. You can chain multiple .query() calls, and they merge together—useful when building queries conditionally.

The .timeout() method accepts either a number (milliseconds) or an object with response and deadline properties. Setting appropriate timeouts prevents your application from hanging indefinitely when services are slow or unresponsive.

Comparison Table

3 Common Mistakes

Mistake 1: Forgetting Error Handling

// ❌ Bad - no error handling
const res = await request.get('https://api.example.com/data');
console.log(res.body);

// ✅ Good - proper error handling
try {
  const res = await request.get('https://api.example.com/data');
  console.log(res.body);
} catch (err) {
  if (err.response) {
    // Server responded with error status
    console.error('Server error:', err.response.status);
  } else {
    // Network error or timeout
    console.error('Network error:', err.message);
  }
}

I see this constantly in code reviews. Superagent throws errors for non-2xx status codes, which is great for error handling but catches developers off guard. Always wrap requests in try-catch blocks. The error object contains a response property if the server responded, making it easy to distinguish between network failures and API errors.

Mistake 2: Not Setting Timeouts

// ❌ Bad - no timeout, request can hang forever
const res = await request.get('https://slow-api.example.com/data');

// ✅ Good - reasonable timeout
const res = await request
  .get('https://slow-api.example.com/data')
  .timeout(5000);

Without timeouts, a slow or unresponsive server can hang your application indefinitely. I learned this the hard way when a third-party API went down and our entire service became unresponsive. Always set timeouts based on your application's requirements. For user-facing requests, 5-10 seconds is reasonable. For background jobs, you might allow longer.

Mistake 3: Ignoring Response Status Codes

// ❌ Bad - assuming success
const res = await request.get('https://api.example.com/users/123');
console.log(res.body.name);

// ✅ Good - checking status explicitly when needed
const res = await request
  .get('https://api.example.com/users/123')
  .ok(res => res.status < 500); // Don't throw on 4xx

if (res.status === 404) {
  console.log('User not found');
} else {
  console.log(res.body.name);
}

By default, Superagent throws on any non-2xx status. Sometimes you want to handle 4xx responses differently than 5xx. The .ok() method lets you customize which status codes are considered successful. This is particularly useful for 404s or 304s where you want to handle the response rather than catch an error.

FAQ

Q: Does Superagent work in both Node.js and browsers?

Yes, Superagent is isomorphic and works seamlessly in both environments. The API is identical, though the underlying implementation differs. In Node.js, it uses the native http module, while in browsers it uses XMLHttpRequest. This makes it perfect for universal/isomorphic applications where you want consistent HTTP handling across server and client. You can write your API client once and use it everywhere. Just be aware of CORS restrictions in browsers that don't apply to Node.js.

Q: How do I cancel a Superagent request?

Superagent supports request cancellation through the .abort() method. Store the request object and call .abort() when needed. This is useful for implementing search-as-you-type features where you want to cancel previous requests when new ones are made. In modern versions, you can also use AbortController for more standard cancellation patterns. The request will throw an error when aborted, so handle it in your catch block by checking for abort-specific error codes.

Q: Can I use Superagent with TypeScript?

Absolutely. Superagent includes TypeScript definitions out of the box. The types are well-maintained and cover the entire API surface. You get full autocomplete and type checking for requests and responses. For even better type safety, you can define interfaces for your API responses and type-cast the res.body property. Many developers prefer Superagent over Axios in TypeScript projects because the chainable API feels more natural with TypeScript's type inference. The types are actively maintained and updated with each release.

Q: How does Superagent handle cookies?

In browsers, Superagent automatically handles cookies through the browser's cookie jar—they're sent and stored automatically. In Node.js, you need to manually manage cookies using the .set('Cookie', ...) method or use a plugin like superagent-use with a cookie jar middleware. For session-based authentication in Node.js, I recommend storing cookies from the login response and including them in subsequent requests. The set-cookie header in responses contains cookies you should persist.

Q: Is Superagent still actively maintained?

Yes, though development has slowed compared to its peak. The library is mature and stable, with most core features complete. Security updates and bug fixes are still released regularly. The community is active, and the library has millions of weekly downloads. That said, if you're starting a new project, consider whether you need Superagent's features or if native fetch (with a small wrapper) might suffice. For existing projects, there's no urgent need to migrate away—Superagent remains a solid, reliable choice.

Conclusion

Superagent transformed how I write HTTP requests. Its chainable API isn't just syntactic sugar—it fundamentally improves code readability and maintainability. When I look at Superagent code six months later, I immediately understand what's happening. The same can't be said for nested fetch calls with manual error handling.

The library's real strength lies in its thoughtful design. Features like automatic JSON parsing, built-in retry logic, and progress events aren't afterthoughts—they're core to the experience. You spend less time fighting with HTTP mechanics and more time building features.

Is Superagent perfect? No. The bundle size matters for some projects, and native fetch is improving. But for Node.js applications, full-stack projects, or anywhere you value developer experience, Superagent remains an excellent choice. It's saved me countless hours of debugging and made my codebases cleaner.

If you're tired of boilerplate HTTP code, give Superagent a try. Start with simple GET requests, then explore the patterns I've shared. You'll quickly discover why thousands of developers trust it for production applications. Sometimes the best tools are the ones that get out of your way and let you focus on what matters.