A lightweight, type-safe React library that abstracts API-related infrastructure code with centralized state management for API operations
npm install react-apiloaderA lightweight, type-safe React library that abstracts API-related infrastructure code, significantly reducing component complexity. React API Loader provides centralized state management for API operations, enables request cancellation, and offers reusable UI components to simplify handling loading, error, and success states.
``bashUsing npm
npm install react-apiloader
Key Features
- 🔄 Centralized API State Management: Track loading and error states for all requests in one place
- 🎣 Type-Safe Hooks: Full TypeScript support with generics for parameters and responses
- ⚡ Simplified Component Architecture: Eliminate repetitive loading/error handling code
- 🚀 Response Transformation: Transform API responses before updating component state
- 🚫 Automatic Request Cancellation: Prevent memory leaks and race conditions
- 🔌 Client Adapter Pattern: Use with any HTTP client (fetch, Axios, etc.)
- 🧩 Flexible State Management: Choose between internal state, external state, or stateless options
- 🛠️ Ready-to-Use UI Components: LoadingButton and RepeatPanel for common UIs
API Reference
The repository includes two example projects that demonstrate the library usage:
1. Minimal Example - A simple demonstration of core API features with basic implementation patterns. This example shows the essential functionality with minimal dependencies.
2. Standard Example - A more comprehensive implementation that demonstrates:
- Recommended folder structure for larger applications
- Integration with global state management
- The
useMessage hook for centralized error handling
- Styling and UI component organization
- Authentication flow integrationThe examples below are based on the minimal implementation. For more advanced patterns, explore the standard example in the repository.
$3
First, import the library and define your client and error types:
`typescript
import {
type AppKey,
type ClientAdapter,
type ClientFactory,
createLoaderApi,
} from 'react-apiloader';// Define the error type for your API
type ClientError = {
description: string | string[];
status?: number;
data?: unknown;
};
// Define your API client interface
interface IFetchClient {
get(url: string, params?: unknown, settings?: RequestInit): Promise;
post(url: string, data?: D, params?: unknown, settings?: RequestInit): Promise;
}
// Create your API loader context and extract the hooks you need
const {
createApiHook,
createApiHookWithState,
createApiHookWithExternalState,
LoaderContextProvider,
useLoaderInfo,
} = createLoaderApi();
`$3
Create a client factory that returns a client implementation and its adapter:
`typescript
const createClientFactory =
(baseUrl: string): ClientFactory => () => {
const controller = new AbortController();
// Client implementation
const client: IFetchClient = {
get: async (url: string, params?: Record, settings?: RequestInit) =>
fetch(createUrl(url, params), {
method: 'GET',
headers: { 'Content-Type': 'application/json' },
signal: controller.signal,
...settings,
})
.then((response) => handleResponse(response)), post: async (
url: string,
data?: D,
params?: Record,
settings?: RequestInit,
) => {
return fetch(createUrl(url, params), {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(data),
signal: controller.signal,
...settings,
})
.then((response) => handleResponse(response));
},
};
// Client adapter for handling cancellation and errors
const adapter: ClientAdapter = {
cancel: () => controller.abort(),
isCanceled: (error: unknown) => error instanceof DOMException && error.name === 'AbortError',
parseError: (error: unknown) => {
console.error('# ERROR #', error);
// Your error parsing logic
return {
description: (error as Error)?.message ?? 'Unknown error',
};
},
};
return [client, adapter];
};
// Create a client factory instance
const clientFactory = createClientFactory('https://jsonplaceholder.typicode.com/');
`$3
The library provides three types of API hooks for different use cases:
#### 1. createApiHook - Stateless Hook
For operations without internal state, like creating/updating resources:
`typescript
// Define a model for your data
interface TodoModel {
userId: number;
id: number;
title: string;
completed: boolean;
}// Create a hook for saving todos
const useSaveTodo = createApiHook(
(http, params) =>
http.post(
todos, params).then((data) => {
// Transform data if needed before returning
return data;
}),
);// Usage in a component
const saveTodoApi = useSaveTodo();
const saveTodo = useCallback(
(todo: TodoModel) => {
// The second parameter sets the mode for parallel requests
void saveTodoApi(todo, todo.id)
.then((result) => {
if (result.isSuccess) {
console.log('Save success:', result.data);
} else if (result.isCanceled) {
console.log('Save canceled');
} else if (result.isError) {
console.log('Error saving:', result.error);
}
});
},
[saveTodoApi],
);
`#### 2. createApiHookWithState - Hook with Internal State
For fetching data with internal state management:
`typescript
// Create a hook for fetching todos with internal state
const useGetTodos = createApiHookWithState(
(http, params) =>
http.get( todos, { userId: params.userId }).then((data) => {
// Transform data if needed
return data;
}),
undefined, // Initial state value
);// Usage in a component
const [todos, getTodosApi] = useGetTodos();
const getTodos = useCallback(() => {
if (user) {
void getTodosApi({ userId: user.id });
}
}, [getTodosApi, user]);
// Call the API on component mount
useEffect(() => void getTodos(), [getTodos]);
// Render the data
return (
{todos?.map((todo) => (
{todo.title}
))}
);
`#### 3. createApiHookWithExternalState - Hook with External State
For updating global/external state sources:
`typescript
interface UserModel {
id: number;
username: string;
}// Using React's useState as an example of an external state
// In real apps, this could be a Redux store, Jotai atom, etc.
const useGetUser = createApiHookWithExternalState(
(http, params) => http.get(
users, { id: params }).then((x) => x[0]),
useState, // External state hook
);// Usage in a component
const [user, getUserApi] = useGetUser();
const getUser = useCallback(() => getUserApi(1), [getUserApi]);
// Call the API on component mount
useEffect(() => void getUser(), [getUser]);
// User state is automatically updated when API call succeeds
return
{'User: ' + (user?.username ?? 'Not found')}
;
`$3
These ready-to-use components help you handle loading and error states consistently:
#### LoadingButton
A button that displays a loading indicator and disables itself while an API call is in progress:
`tsx
export type LoadingButtonProps = {
actionType: AppKey;
mode?: AppKey;
children: React.ReactNode;
disabled?: boolean;
onClick?: (e: React.MouseEvent) => void;
};export const LoadingButton: FC = ({
actionType,
mode = undefined,
children,
disabled,
onClick,
}) => {
// Get the current state of the specified API call
const item = useLoaderInfo(actionType, mode);
const isDisabled = item?.isWaiting || disabled;
return (
);
};
`#### RepeatPanel
A component that handles loading, error, and success states:
`tsx
interface RepeatPanelProps {
actionType: AppKey;
mode?: AppKey;
action: () => void;
children: React.ReactNode;
}export const RepeatPanel: FC = ({ actionType, mode, action, children }) => {
// Get the current state of the specified API call
const item = useLoaderInfo(actionType, mode);
if (item?.isWaiting) return
Loading...; if (item?.isError)
return (
Cannot get data from the server
); return <>{children}>;
};
`$3
Wrap your application with the
LoaderContextProvider:`tsx
// Root component
const App = () => {
// Your application components
return React API Loader Example
;
};// Render with the provider
ReactDOM.createRoot(document.getElementById('root') as Element).render(
,
);
`$3
Here's a complete example showing how everything works together:
`tsx
const App = () => {
// User data with external state
const [user, getUserApi] = useGetUser();
const getUser = useCallback(() => getUserApi(1), [getUserApi]);
useEffect(() => void getUser(), [getUser]); // Todos with internal state
const [todos, getTodosApi] = useGetTodos();
const getTodos = useCallback(() => {
if (user) {
void getTodosApi({ userId: user.id });
}
}, [getTodosApi, user]);
useEffect(() => void getTodos(), [getTodos]);
// Stateless API for saving todos
const saveTodoApi = useSaveTodo();
const saveTodo = useCallback(
(todo: TodoModel) => {
void saveTodoApi(todo, todo.id)
.then((x) => {
if (x.isSuccess) {
console.log('Save success:', x.data);
} else if (x.isCanceled) {
console.log('Save canceled');
} else if (x.isError) {
console.log('Error saving todo:', x.error);
}
});
},
[saveTodoApi],
);
return (
<>
React API Loader Minimal Example
{'User: ' + (user?.username ?? 'Not found')}
Todos
Refresh
{todos?.map((todo) => (
{todo.title}
actionType={useSaveTodo.id}
onClick={() => saveTodo(todo)}
// Set mode to track specific request state
mode={todo.id}>
Save
))}
>
);
};
`Additional Information
$3
Automatically cancel API calls when a component unmounts:
`tsx
function SearchComponent() {
const searchApi = useSearch();
// This will automatically cancel pending search requests
// when the component unmounts
useCancellation(useSearch.id);
// Component implementation
}
`$3
Manually cancel API calls from anywhere:
`tsx
function SearchWithCancel() {
const searchApi = useSearch();
const cancelAction = useCancelAction();
return (
);
}
`$3
Process API responses globally before they reach components:
`tsx
// Create an interceptor
const clientInterceptorHook: ClientInterceptorHook = () => {
return (result) => {
// Log all API responses
console.log('API response:', result);
// Handle specific errors globally
if (result.isError && result.error.status === 401) {
// Redirect to login page or show an auth error
window.location.href = '/login';
}
// Show a toast notification for errors
const [addToast] = useToaster();
if (result.isError) {
addToast({
type: 'error',
message: result.error.description,
});
}
// Return the result to continue processing
return result;
};
};// Provide the interceptor to the context
clientFactory={clientFactory}
clientInterceptorHook={clientInterceptorHook}>
`$3
The
mode parameter allows handling multiple concurrent API calls of the same type:`tsx
// Create a stateless hook
const useSearchProducts = createApiHook(
(client, params) => client.get( /search?q=${params.query}),
);function SearchPage() {
const searchApi = useSearchProducts();
// Execute multiple parallel searches with different modes
const searchBooks = () => searchApi({ query: 'books' }, 'books');
const searchMovies = () => searchApi({ query: 'movies' }, 'movies');
return (
Product Search
{/ LoadingButton handles waiting state automatically /}
actionType={useSearchProducts.id}
mode="books"
onClick={searchBooks}>
Search Books
actionType={useSearchProducts.id}
mode="movies"
onClick={searchMovies}>
Search Movies
);
}
``MIT © Max Grekhov