newexpand-nextjs-fetch
v1.1.0
Published
extend nextjs fetch api
Downloads
21
Maintainers
Readme
※ This document is based on version 1.1.0.
newexpand-nextjs-fetch
The newexpand-nextjs-fetch
library is a utility designed to enhance the capabilities of the native fetch API in Next.js 14, providing a more powerful and flexible way to make HTTP requests. It introduces features such as request and response interceptors, automatic handling of different content types, request cancellation, and configurable timeouts, making it an ideal choice for developers looking for an extended fetch utility in their Next.js projects.
Features
newexpand-nextjs-fetch
is designed to enhance the developer experience by providing a suite of features that make HTTP requests more manageable and efficient in Next.js applications. Here are some of the key features:
- Configurable Base URL: Set a base URL for all your requests, simplifying the management of API endpoints across your application.
- Timeouts: Define a global timeout for all requests to ensure your application remains responsive, even if a server response is delayed.
- Request and Response Interceptors: Interceptors allow you to modify requests before they are sent and responses before they are processed. This is useful for adding headers, logging, or handling errors globally.
- Automatic Retries: Configure automatic retries for requests that fail due to network issues or server errors, improving the reliability of your application.
- Request Cancellation: Cancel in-flight requests using a unique request ID, giving you control over resource usage and network traffic.
- Automatic Content Type Handling: Automatically handles JSON, text, FormData, Blob, and more based on the Content-Type.
- Flexible Body Types: Supports various body types, including
FormData
,URLSearchParams
,Blob
, and more, allowing you to easily work with different content types. - TypeScript Support: Comes with TypeScript definitions out of the box, providing auto-completion and type checking to enhance development speed and reduce errors.
Installation
To install the library, run the following command in your project directory:
bash
npm install newexpand-nextjs-fetch
#or
yarn add newexpand-nextjs-fetch
Usage
First, import the createCustomFetch
function from the library:
import { createCustomFetch, type Config } from "newexpand-nextjs-fetch";
Creating an Instance
Create a custom fetch instance with optional configuration:
// typescript
import { createCustomFetch, Config } from "newexpand-nextjs-fetch";
const config: Config = {
baseUrl: "https://api.example.com",
timeout: 10000, // 10 seconds
retryAttempts: 2,
retryDelay: 2000, // 2 seconds
headers: {
"Content-Type": "application/json",
},
};
const myFetch = createCustomFetch(config);
Request and Response Interceptors**
You can add multiple request and response interceptors, including asynchronous ones.
Adding a Request Interceptor
// typescript
config.requestInterceptors = [
async (requestOptions) => {
// Add a token to the request headers
requestOptions.headers = {
...requestOptions.headers,
Authorization: `Bearer YOUR_TOKEN_HERE`,
};
return requestOptions;
},
];
Adding a Response Interceptor
// typescript
config.responseInterceptors = [
async (response) => {
// Check for a specific condition in the response
if (!response.ok) {
throw new Error("An error occurred");
}
return response;
},
];
Making HTTP Requests
GET Request
// typescript
const fetchData = async () => {
const { data, isLoading, isError } = await myFetch.get("/path/to/resource");
if (isError) {
console.error("Error fetching data");
return;
}
if (isLoading) {
console.log("Loading...");
return;
}
console.log("Data:", data);
};
POST Request
// typescript
const postData = async () => {
const body = { key: "value" };
const { data, isLoading, isError } = await myFetch.post(
"/path/to/resource",
body
);
// Handle response as in the GET example
};
Canceling a Request
You can cancel a request using the cancelRequest method. Each request is identified by a unique ID.
// typescript
const requestId = "unique-request-id";
// Start a request
myFetch.get("/path/to/resource", {}, requestId);
// Cancel the request
myFetch.cancelRequest(requestId);
Supported Body Types
When making POST
, PUT
, PATCH
, or DELETE
requests, you can send data in various formats. Below is a table of the supported body types and their descriptions, ensuring you can work with a wide range of content types effectively.
| Body Type | Description |
| ----------------- | -------------------------------------------------------------------------------------------- |
| string
| A plain text string. Useful for sending JSON as a string after using JSON.stringify()
. |
| FormData
| Use for multipart/form-data requests, such as file uploads. |
| URLSearchParams
| Encodes data as query string parameters. Useful for form submissions. |
| Blob
| Use for binary data, such as files. |
| ArrayBuffer
| Use for binary data when you need to manipulate the bytes before sending. |
| ArrayBufferView
| A view on an ArrayBuffer
(e.g., Uint8Array
, Float32Array
). For binary data operations. |
| ReadableStream
| A stream of data. Useful for uploading large files without reading them into memory first. |
| null
| Indicates no body should be sent with the request. |
| undefined
| Similar to null
, it indicates that no body is set, resulting in no body being sent. |
Automatic Content Type Handling
newexpand-nextjs-fetch
simplifies the handling of different response types by automatically processing the response based on the Content-Type
header. This feature ensures that you receive the data in the appropriate format without needing to manually parse the response for common content types.
Below is a table detailing how different Content-Type
responses are handled:
| Content-Type | Handled As | Description |
| -------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------- |
| application/json
| JSON | Automatically parsed into a JavaScript object. |
| text/*
| Text | Treated as plain text, including text/html
, text/plain
, etc. |
| multipart/form-data
| FormData | Returned as FormData
, useful for processing forms and file uploads. |
| image/*
, application/pdf
, application/octet-stream
| Blob | Binary data, including images and PDFs, is returned as a Blob
. |
| Other
| Error Thrown | If the content type is not supported, an error is thrown indicating the unsupported type. |
|
Advanced Configuration
The Config
object allows for advanced configuration such as setting custom headers, configuring retry attempts and delays, and more. Refer to the Config interface for all available options.
Contributing
Contributions are welcome! If you have suggestions or want to improve the library, feel free to create issues or pull requests on the GitHub repository.
License
This library is open-sourced software licensed under the MIT license.