React API Forge

A flexible and robust React hook factory for creating API hooks with consistent patterns. Build type-safe, reusable API hooks with built-in loading states, error handling, and request cancellation.

✨ Features

• 🎣 Consistent API patterns - Create uniform API hooks across your application
• 🔄 Built-in state management - Loading states, error handling, and response caching
• 🎯 Full TypeScript support - Type-safe hooks with intelligent autocompletion
• 🛑 Request cancellation - Automatic cleanup on component unmount
• 🔧 Flexible configuration - Path parameters, query parameters, and custom validation
• 📦 Lightweight - Minimal dependencies, built on Axios
• 🎨 Callback support - onSuccess and onError callbacks for custom handling
• ⚡ Modern React - Built for React 16.8+ with hooks

📦 Installation

NPM

npm install react-api-forge

yarn add react-api-forge

pnpm add react-api-forge

GitHub Packages

npm install @Xarlizard/react-api-forge

Note: For GitHub Packages, you'll need to configure your .npmrc file. See PUBLISHING.md for details.

🚀 Quick Start

import { createApiHook } from "react-api-forge";

// Create a typed API hook with unified options array
const useGetUser = createApiHook({
  method: "GET",
  baseURL: "https://api.example.com",
  endpoint: "/users/:userId",
  // Path params are automatically extracted from endpoint
  options: [
    {
      key: "lang",
      location: "query",
      defaultValue: "en_US",
      // Optional (has defaultValue, so implicitly optional)
    },
  ],
});

// Use in your component
const UserProfile = ({ userId }) => {
  const { response, error, loading, fetchData } = useGetUser();

  useEffect(() => {
    fetchData({
      path: { userId },
      query: { lang: "es_ES" }
    });
  }, [userId]);

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error}</div>;

  return <div>Hello, {response?.name}!</div>;
};

// Actual API call:
// https://api.example.com/users/:userId?lang=es_ES

📚 API Reference

createApiHook(config)

Creates a custom API hook with the specified configuration.

Configuration Options

Property	Type	Required	Description
method	Method	✅	HTTP method (GET, POST, PUT, DELETE, PATCH, etc.)
baseURL	string	✅	Base URL for the API endpoint
endpoint	string	✅	Endpoint path (path params like :userId are auto-extracted)
options	ApiParam[]	❌	Array of parameter definitions (query, header, body only)
headers	object	❌	Custom headers for requests
validateResponse	function	❌	Function to validate response data
transformResponse	function	❌	Function to transform response data
onError	function	❌	Global error handler function
functionName	string	❌	Custom function name (auto-generated from method if not provided)

ApiParam Interface

Each parameter in the options array is defined using the ApiParam interface:

Property	Type	Required	Description
key	string	✅	Parameter name/key
location	ParamLocation	✅	Where the parameter is used: "query", "header", "body" (path params are auto-extracted from endpoint)
required	boolean	❌	Whether the parameter is required from the user's perspective. Important: If defaultValue is provided, this parameter is automatically optional (the required flag is ignored). The API will always receive a value (either user-provided or the default), but users don't need to provide it. - Options with defaultValue are optional (implicit) - required is ignored - Only specify required: true for options without defaultValue that must be provided
defaultValue	any	❌	Default value for the parameter. If provided, the option is automatically optional (users don't need to provide it), and the API will always receive a value (either user-provided or this default)
valueType	T	❌	Type hint for TypeScript inference (runtime ignored)

Note: Path parameters are automatically extracted from the endpoint string (e.g., /users/:userId extracts userId). You don't need to define them in the options array.

Returned Hook

The generated hook returns an object with:

Property	Type	Description
response	T | null	The response data from the API call
error	any | null	Error information if the request failed
loading	boolean	Loading state indicator
fetchData	function	Function to trigger the API call (for GET requests)
postData	function	Function to trigger the API call (for POST requests)
putData	function	Function to trigger the API call (for PUT requests)
patchData	function	Function to trigger the API call (for PATCH requests)
deleteData	function	Function to trigger the API call (for DELETE requests)

Function Name Auto-Generation:

• GET → fetchData
• POST → postData
• PUT → putData
• PATCH → patchData
• DELETE → deleteData

Function Signature:

functionName(options: {
  path?: Record<string, any>;
  header?: Record<string, any>;
  body?: Record<string, any>;
  query?: Record<string, any>;
}, callbacks?: {
  onSuccess?: (data: T) => void;
  onError?: (error: any) => void;
}): void

📖 Examples

GET Request with Path Parameters

const useGetPost = createApiHook({
  method: "GET",
  baseURL: "https://jsonplaceholder.typicode.com",
  endpoint: "/posts/:postId",
  // Path params are automatically extracted from endpoint
});

// Usage
const { response, loading, error, fetchData } = useGetPost();

useEffect(() => {
  fetchData({
    path: { postId: "1" }
  });
}, []);

POST Request with Callbacks

const useCreateUser = createApiHook({
  method: "POST",
  baseURL: "https://api.example.com",
  endpoint: "/users",
  options: [
    {
      key: "name",
      location: "body",
      required: true,
    },
    {
      key: "email",
      location: "body",
      required: true,
    },
  ],
  // functionName is automatically "postData" for POST requests
});

// Usage
const { loading, error, postData } = useCreateUser();

const handleSubmit = () => {
  postData({
    body: {
      name: "John Doe",
      email: "[email protected]"
    }
  }, {
    onSuccess: (newUser) => {
      console.log("User created:", newUser);
      router.push(`/users/${newUser.id}`);
    },
    onError: (error) => {
      console.error("Failed to create user:", error);
      setFormError(error.message);
    },
  });
};

GET Request with Query Parameters

const useSearchUsers = createApiHook({
  method: "GET",
  baseURL: "https://api.example.com",
  endpoint: "/users/search",
  options: [
    {
      key: "query",
      location: "query",
      // Optional (no defaultValue, no required: true)
    },
    {
      key: "limit",
      location: "query",
      defaultValue: 10,
      // Optional (has defaultValue, so implicitly optional)
    },
    {
      key: "offset",
      location: "query",
      defaultValue: 0,
      // Optional (has defaultValue, so implicitly optional)
    },
  ],
});

// Usage
const { response, fetchData } = useSearchUsers();

useEffect(() => {
  fetchData({
    query: {
      query: "React",
      limit: 20,
    }
  });
}, []);

Typed Parameters with Type Safety

import { createApiHook, param } from "react-api-forge";

type LanguageCode = "en_US" | "en_GR" | "es_ES";

const useGetUser = createApiHook({
  method: "GET",
  baseURL: "https://api.example.com",
  endpoint: "/users/:userId",
  // Path params are automatically extracted from endpoint
  options: [
    param<LanguageCode>({
      key: "lang",
      location: "query",
      defaultValue: "en_US",
      // Optional (has defaultValue, so implicitly optional)
    }),
  ],
});

// Usage - TypeScript will enforce correct types
fetchData({
  path: { userId: "123" },
  query: { lang: "en_GR" }
}); // ✅ Valid
fetchData({
  path: { userId: "123" },
  query: { lang: "fr_FR" }
}); // ❌ Type error
fetchData({
  path: { userId: "123" }
}); // ✅ Valid (lang uses default "en_US")

Response Transformation

const useGetUserProfile = createApiHook({
  method: "GET",
  baseURL: "https://api.example.com",
  endpoint: "/users/:userId/profile",
  // Path params are automatically extracted from endpoint
  transformResponse: (data) => ({
    ...data,
    fullName: `${data.firstName} ${data.lastName}`,
    avatar: data.avatarUrl || "/default-avatar.png",
  }),
  validateResponse: (data) => data && typeof data.firstName === "string",
});

Error Handling

const useApiCall = createApiHook({
  method: "GET",
  baseURL: "https://api.example.com",
  endpoint: "/data",
  onError: (error) => {
    // Global error handling
    if (error.response?.status === 401) {
      // Redirect to login
      window.location.href = "/login";
    }
    return error.response?.data?.message || "An error occurred";
  },
});

🔧 Advanced Usage

Custom Headers and Authentication

const useAuthenticatedRequest = createApiHook({
  method: "GET",
  baseURL: "https://api.example.com",
  endpoint: "/protected-data",
  headers: {
    Authorization: `Bearer ${getAuthToken()}`,
    "Content-Type": "application/json",
  },
});

Multiple Path Parameters

const useGetData = createApiHook({
  method: "GET",
  baseURL: "https://api.example.com",
  endpoint: "/users/:userId/posts/:postId",
  // Multiple path params are automatically extracted
});

// Usage
fetchData({
  path: {
    userId: "123",
    postId: "456"
  }
});

Complex Example with Header Parameters

const useAuthenticatedRequest = createApiHook({
  method: "GET",
  baseURL: "https://api.example.com",
  endpoint: "/protected-data/:resourceId",
  // Path params are automatically extracted from endpoint
  options: [
    {
      key: "Authorization",
      location: "header",
      required: true,
      // Explicitly required (no defaultValue)
    },
    {
      key: "version",
      location: "query",
      defaultValue: "v1",
      // Optional (has defaultValue, so implicitly optional)
    },
  ],
});

// Usage
fetchData({
  path: {
    resourceId: "123"
  },
  header: {
    Authorization: `Bearer ${token}`
  },
  query: {
    version: "v2"
  }
});

🤝 TypeScript Support

React API Forge is built with TypeScript and provides full type safety:

interface User {
  id: number;
  name: string;
  email: string;
}

const useGetUser = createApiHook<User>({
  method: "GET",
  baseURL: "https://api.example.com",
  endpoint: "/users/:userId",
  // Path params are automatically extracted from endpoint
  options: [
    {
      key: "includeProfile",
      location: "query",
      // Optional (no defaultValue, no required: true)
    },
  ],
});

// TypeScript will enforce correct prop types
const { response } = useGetUser();
// response is typed as User | null

// Usage with grouped params
fetchData({
  path: { userId: "123" },
  query: { includeProfile: true }
});

🛠️ Requirements

• React 16.8.0 or higher
• Axios 0.21.0 or higher

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with Axios for HTTP requests
• Inspired by modern React patterns and hooks
• TypeScript support for better developer experience

---

Made with ❤️ by Xarlizard