@ahsan-iftikhar-114/api-toolkit-fetch

A lightweight React API toolkit for React and TypeScript applications, built directly on the native Fetch API.

It provides a simple and reusable way to create API requests and React API hooks without requiring Axios, Redux, or TanStack Query.

What Is This Package?

@ahsan-iftikhar-114/api-toolkit-fetch is a lightweight API client and React API hooks package designed for applications that need a simple way to communicate with REST APIs.

It provides a consistent API layer for:

• GET requests
• POST requests
• PUT requests
• PATCH requests
• DELETE requests
• Authentication
• Request headers
• Query parameters
• Request bodies
• Loading states
• Success states
• Error handling
• Request timeout
• Request cancellation
• Refetching
• TypeScript support

Purpose

The purpose of this package is to make API communication in React applications simpler and more reusable.

Instead of creating separate Fetch API logic for every request, developers can define reusable API endpoints and use the generated React hooks throughout their application.

The package is designed for developers who want a lightweight API solution without adding a larger API state-management library.

Why Use This Package?

This package is useful when a React application needs API communication but does not require Axios, Redux, or TanStack Query.

It provides:

• A simple API creation system
• Reusable React API hooks
• Native Fetch API support
• Centralized API configuration
• Authentication support
• Request lifecycle states
• Standardized API errors
• Request timeout and cancellation
• TypeScript generics
• REST API compatibility
• Minimal dependencies

Main Function

The main function of the package is:

createApi(name, method, url)

This function creates a reusable API hook based on the HTTP method.

GET APIs create query-style hooks.

POST, PUT, PATCH, and DELETE APIs create mutation-style hooks.

API configuration is handled separately through:

configureApi()

The package also exports getApiConfig(), resetApiConfig(), and the low-level request() function for applications that need request handling without a generated React hook.

How It Works

The package follows a simple API request flow:

createApi → React Hook → API Request → Native Fetch API → Response / ApiError → React State

This keeps API request logic separated from individual React components while providing reusable request states.

Supported HTTP Methods

The package supports:

• GET
• POST
• PUT
• PATCH
• DELETE

React API Hooks

The package provides two core React hook systems:

useApi()

Used internally for GET API requests.

useApiMutation()

Used internally for POST, PUT, PATCH, and DELETE requests.

Developers normally interact with these hooks through createApi() rather than using the lower-level hooks directly.

API Configuration

Global API settings can be configured through configureApi().

Supported configuration includes:

• Base URL
• Global headers
• Authentication token
• Dynamic token provider
• Request timeout
• Credentials
• Request mode
• Cache behavior
• Redirect behavior
• Referrer policy

This allows common API settings to be configured once and reused across multiple API endpoints.

Authentication

The package supports API authentication through:

• Static authentication tokens
• Dynamic token providers
• Automatic Bearer Authorization headers
• Custom Authorization headers

Applications remain responsible for deciding how authentication credentials are stored and managed.

Request Configuration

Requests support common Fetch API configuration such as:

• Headers
• Query parameters
• Request body
• Abort signals
• Timeout
• Credentials
• Mode
• Cache
• Redirect
• Referrer policy

Request-specific configuration can be used alongside global configuration.

Query Parameters

GET API requests support query parameters through standard parameter objects and URLSearchParams.

Null and undefined parameter values are ignored.

Parameters are encoded before being added to the request URL.

Request Bodies

The package supports request bodies for API mutations.

Common body types supported by the Fetch API include:

• JSON objects
• FormData
• Blob
• ArrayBuffer
• URLSearchParams
• Strings

Object request bodies are automatically converted to JSON when an appropriate content type has not already been provided.

Request bodies are supported for POST, PUT, PATCH, and DELETE requests. GET requests do not send a request body.

Loading and Success States

API hooks provide request lifecycle states including:

• loading
• success
• data
• error

These states allow React applications to manage API-driven UI without creating separate request-state logic for every endpoint.

Error Handling

The package provides a standardized ApiError class for API failures.

An API error can contain information such as:

• Error message
• HTTP status
• Status text
• Response data
• Validation errors
• Original error
• Cancellation state
• Timeout state

HTTP errors, network errors, cancelled requests, timeout errors, and response parsing errors can be handled through the package error system.

Request Timeout

API requests can use configurable timeout values.

Timeouts can be configured globally or for individual requests.

Timeout information is available through the API error state.

Request Cancellation

The package uses the native browser AbortController API for request cancellation.

GET and mutation requests support cancellation.

Pending requests are also safely cancelled when the associated React component is unmounted.

Refetching

GET API hooks support manual refetching.

This allows an application to execute an existing GET request again when updated data is required.

Mutation Management

Mutation hooks support:

• Loading state
• Success state
• Error state
• Response data
• Request cancellation
• Resetting mutation state
• Success callbacks
• Error callbacks
• Settled callbacks

Mutation options also support query parameters through params.

TypeScript Support

The package is written in TypeScript and provides generic types for API responses and request bodies.

This allows developers to define strongly typed API responses and mutation payloads.

TypeScript declarations are generated during the package build process.

Native Fetch API

This package is built directly on the native Fetch API.

It does not use Axios or another third-party HTTP client.

This keeps the package lightweight and allows applications to work with standard Fetch API behavior.

No Axios Required

Axios is not required.

The package uses the native Fetch API for HTTP requests.

No Redux Required

Redux and Redux Toolkit are not required.

The package manages API request state through its own React hooks.

No TanStack Query Required

TanStack Query is not required.

The package provides its own lightweight API request and mutation handling.

Common Use Cases

The package is suitable for:

• React applications
• React TypeScript applications
• REST API integrations
• CRUD applications
• Admin dashboards
• Authentication APIs
• User management systems
• Product management systems
• Form-based API requests
• Business applications
• Lightweight frontend API clients

Backend Compatibility

The package can communicate with REST APIs built with any backend technology that supports HTTP requests.

It can be used with APIs built using technologies such as:

• Laravel
• PHP
• Node.js
• Express
• Django
• .NET
• Java
• Spring
• Ruby on Rails
• Other REST API platforms

Browser and Runtime Requirements

The package is designed primarily for React applications running in environments that provide the standard Fetch API and AbortController APIs.

Applications using environments without these APIs may require appropriate polyfills or runtime support.

Important Considerations

This package is intentionally focused on API request handling and lightweight React API state.

It does not attempt to replace full server-state management solutions.

It does not provide features such as:

• Automatic query caching
• Query invalidation
• Background polling
• Infinite queries
• Offline synchronization
• Persistent server-state caching

Applications requiring advanced server-state management may need a dedicated solution.

Public API

The primary public function is:

createApi(name, method, url, config?)

Configuration functions include:

• configureApi()
• getApiConfig()
• resetApiConfig()

Request function:

• request()

Error utilities include:

• createTimeoutError()

The package also exports the relevant TypeScript types and the ApiError class. The internal hook and error-construction helpers are intentionally not part of the public API.

Installation

Install the package using npm:

npm install @ahsan-iftikhar-114/api-toolkit-fetch

The package requires React 18 or newer.

For TypeScript projects, TypeScript and React type definitions should also be installed if they are not already available in the project.

Package Characteristics

• Lightweight
• TypeScript-first
• React-focused
• Native Fetch API
• REST API compatible
• Minimal dependencies
• Reusable API hooks
• Centralized configuration
• Request cancellation
• Request timeout
• Authentication support
• Standardized error handling

Validation

The package provides npm run build for TypeScript compilation, npm test for request-layer tests, and npm run check to run both. Run npm run check before publishing a release.

License

MIT License.

Author

Ahsan Iftikhar