react-query-fusion

A universal data fetching & caching layer combining React Query + Axios + API metadata.

Features

• One declarative hook to fetch & cache data
• One declarative hook for mutations (REST, GraphQL, tRPC)
• Auto-generate loaders, advanced skeletons (customizable)
• Retry logic
• Auto-refetch on focus
• Works across REST, GraphQL, tRPC
• UI helpers for loading, error, and success states (queries & mutations)
• Zero configuration required - includes React Query setup

Why?

Data fetching is still boilerplate-heavy. This package aims to simplify and unify data fetching in React apps.

Comparison with Other Packages

Feature	react-query-fusion	React Query (TanStack)	SWR	Apollo Client	RTK Query
Setup Complexity	✅ Zero config	❌ Manual setup	❌ Manual setup	❌ Complex setup	❌ Complex setup
Multi-Source Support	✅ REST, GraphQL, tRPC	❌ Manual implementation	❌ Manual implementation	❌ GraphQL only	❌ REST only
Built-in UI Helpers	✅ Loading, Error, Success skeletons	❌ Manual implementation	❌ Manual implementation	❌ Manual implementation	❌ Manual implementation
Advanced Skeletons	✅ Customizable shimmer, cards	❌ None	❌ None	❌ None	❌ None
Mutation Support	✅ Unified API	✅ Manual setup	✅ Manual setup	✅ GraphQL only	✅ REST only
Bundle Size	✅ Lightweight	✅ Lightweight	✅ Lightweight	❌ Heavy	❌ Heavy
Learning Curve	✅ Minimal	❌ Steep	❌ Moderate	❌ Steep	❌ Steep
TypeScript Support	✅ First-class	✅ First-class	✅ Good	✅ Good	✅ Good
Caching Strategy	✅ Intelligent	✅ Intelligent	✅ Good	✅ Good	✅ Good
Error Handling	✅ Built-in UI	❌ Manual	❌ Manual	❌ Manual	❌ Manual

Why Choose react-query-fusion?

🚀 Zero Configuration

• No need to install or configure React Query separately
• Single FusionProvider sets up everything automatically
• Works out of the box with any React app

🔄 Universal Data Sources

• One API for REST, GraphQL, and tRPC
• No need to learn different libraries for different data sources
• Consistent patterns across your entire app

🎨 Built-in UI Components

• Advanced skeleton loading states with shimmer effects
• Customizable error and success components
• No more writing boilerplate loading/error UI

⚡ Developer Experience

• Minimal learning curve
• Consistent API across all data sources
• TypeScript-first design
• Comprehensive error handling

📦 Lightweight & Efficient

• Built on top of battle-tested React Query
• Small bundle size
• Optimized for performance

Installation

npm install react-query-fusion

Quick Start

import { FusionProvider, useFusionQuery } from 'react-query-fusion';

function App() {
  return (
    <FusionProvider>
      <Todos />
    </FusionProvider>
  );
}

function Todos() {
  const { data, isLoading, error } = useFusionQuery({
    key: ['todos'],
    source: 'rest',
    url: 'https://jsonplaceholder.typicode.com/todos',
  });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  
  return (
    <ul>
      {data?.map(todo => <li key={todo.id}>{todo.title}</li>)}
    </ul>
  );
}

Usage Examples

Query Example

import { useFusionQuery } from 'react-query-fusion';

const { data, isLoading, error, refetch } = useFusionQuery({
  key: ['todos'],
  source: 'rest',
  url: '/api/todos',
  method: 'GET',
});

Mutation Example

import { useFusionMutation } from 'react-query-fusion';

const { mutate, isLoading, error, isSuccess } = useFusionMutation({
  source: 'rest',
  url: '/api/todos',
  method: 'POST',
});

// Usage:
// mutate({ title: 'New Todo' })

Advanced Skeletons & UI Helpers

import { useFusionQueryUI, FusionProvider } from 'react-query-fusion';

const CustomSkeleton = () => <div className="shimmer-skeleton" />;

const Todos = () => {
  const { data, Loading, ErrorFallback } = useFusionQueryUI({
    key: ['todos'],
    source: 'rest',
    url: '/api/todos',
    skeletonComponent: <CustomSkeleton />,
  });
  if (!data) return <Loading />;
  return <ul>{data.map(todo => <li key={todo.id}>{todo.title}</li>)}</ul>;
};

// Wrap your app
function App() {
  return (
    <FusionProvider>
      <Todos />
    </FusionProvider>
  );
}

API

FusionProvider

The main provider that sets up everything automatically:

• queryClient: Optional custom QueryClient
• loadingComponent: Global loading component
• errorComponent: Global error component
• successComponent: Global success component (for mutations)

useFusionQuery(options)

• key: React Query key (array or string)
• source: 'rest' | 'graphql' | 'trpc'
• url: Endpoint (for REST/GraphQL)
• method: HTTP method (for REST)
• query: GraphQL query (for GraphQL)
• trpcClient: tRPC client instance (for tRPC)
• trpcPath: tRPC path (for tRPC)
• variables: Variables for GraphQL/tRPC
• params: Query params for REST
• data: POST body for REST
• meta: API metadata (optional)
• options: React Query options (optional)

useFusionMutation(options)

• source: 'rest' | 'graphql' | 'trpc'
• url: Endpoint (for REST/GraphQL)
• method: HTTP method (for REST, default 'POST')
• mutation: GraphQL mutation (for GraphQL)
• trpcClient: tRPC client instance (for tRPC)
• trpcPath: tRPC path (for tRPC)
• variables: Variables for GraphQL/tRPC
• params: Query params for REST
• data: POST body for REST
• meta: API metadata (optional)
• options: React Query mutation options (optional)

UI Helpers

• useFusionQueryUI and useFusionMutationUI provide Loading, ErrorFallback, and (for mutations) SuccessFallback components, customizable via props or provider.

License

MIT