Aurelia Fetch Client

1.8.2 · active · verified Tue Apr 21

aurelia-fetch-client provides a straightforward HTTP client built upon the standard Fetch API, tailored for use within the Aurelia framework ecosystem. It is currently at version 1.8.2 and receives updates with a relatively moderate cadence, primarily for bug fixes and minor feature enhancements. Key differentiators include its seamless integration with Aurelia's dependency injection and plugin system, offering features like request interception, retry functionality (since 1.4.0), and helper methods for common HTTP verbs. While designed for Aurelia, it can function in any JavaScript environment, though a Fetch API polyfill (e.g., `whatwg-fetch`) is often required for broader browser or Node.js compatibility. It ships with TypeScript types, facilitating robust development.

Common errors

```
ReferenceError: fetch is not defined
```
cause The environment where `aurelia-fetch-client` is running does not natively provide the Fetch API.

fix Install a Fetch polyfill (e.g., `whatwg-fetch`) and import it before `aurelia-fetch-client` usage: `import 'whatwg-fetch';`
```
Error: Cannot find module 'aurelia-fetch-client'
```
cause The package is not installed or the module resolver cannot find it.

fix Ensure the package is installed (`npm install aurelia-fetch-client`) and that your bundler/runtime is configured to resolve node_modules.
```
TypeError: client.post is not a function
```
cause Attempting to use `post`, `get`, `put`, `delete` helper methods on an older version of `HttpClient`.

fix These helper methods were added in version 1.5.0. Upgrade `aurelia-fetch-client` to version 1.5.0 or higher to use them.

Warnings

gotcha When running in environments that do not natively support the Fetch API (e.g., older browsers or some Node.js versions), a polyfill like `whatwg-fetch` is required. The library itself does not bundle one.
Fix: Install `whatwg-fetch` (`npm install whatwg-fetch`) and import it at the application entry point: `import 'whatwg-fetch';`
breaking Version 1.8.0 introduced a conversion to TypeScript. While largely compatible, subtle type changes or stricter compilation might affect existing JavaScript codebases relying on implicit behaviors or incorrect typings.
Fix: Review type definitions and ensure proper typing when upgrading. If using JavaScript, be aware of potentially stricter runtime checks in some edge cases introduced by the TS conversion.
gotcha The `json()` helper function for POST/PUT requests automatically sets the `Content-Type` header to `application/json` and stringifies the body. If you manually set `Content-Type` or provide a pre-stringified body, it might lead to unexpected header or body formats.
Fix: Use `json(data)` exclusively for automatically handling JSON serialization and content-type. For other content types or pre-stringified data, set `headers` and `body` directly in `RequestInit`.
gotcha Between versions 1.8.0 and 1.8.1/1.8.2, there were changes related to ES2015 module output, specifically reverting 'es2015 back to native-modules'. This could impact build processes or module resolution in specific tooling setups if not aligned with the expected module format.
Fix: If experiencing module resolution issues, ensure your build setup correctly handles native ESM or CommonJS. Upgrading to 1.8.1 or later generally resolves the specific `es2015 back to native-modules` issue.

Install

npm install aurelia-fetch-client npm
yarn add aurelia-fetch-client yarn
pnpm add aurelia-fetch-client pnpm

Imports

HttpClient

wrong:

const HttpClient = require('aurelia-fetch-client').HttpClient;

correct:

import { HttpClient } from 'aurelia-fetch-client';

Primary class for making HTTP requests. Aurelia applications typically inject this.

json
wrong:
```
import { JSON } from 'aurelia-fetch-client';
```
correct:
```
import { json } from 'aurelia-fetch-client';
```
A helper function for setting the Content-Type header to `application/json` and stringifying the body. Note the lowercase 'j'.
RequestInit
```
import { RequestInit } from 'aurelia-fetch-client';
```
TypeScript interface for Fetch API request options, re-exported for convenience and type safety.

Quickstart

Demonstrates initializing HttpClient, configuring a base URL, and performing GET and POST requests with JSON data.

import { HttpClient, json } from 'aurelia-fetch-client';

// For environments without native Fetch, a polyfill is needed.
// import 'whatwg-fetch'; // Polyfill example

async function fetchData() {
  const client = new HttpClient();

  try {
    // Configure the client globally or per-request
    client.configure(config => {
      config
        .useStandardConfiguration()
        .withBaseUrl('https://jsonplaceholder.typicode.com/');
    });

    // Make a GET request
    const getResponse = await client.fetch('posts/1');
    const getData = await getResponse.json();
    console.log('GET Data:', getData);

    // Make a POST request with JSON payload
    const postResponse = await client.post('posts', json({
      title: 'foo',
      body: 'bar',
      userId: 1,
    }));
    const postData = await postResponse.json();
    console.log('POST Data:', postData);

  } catch (error) {
    console.error('Fetch error:', error);
  }
}

fetchData();

view raw JSON →