use-resource

A lightweight React library for efficient data fetching and caching with built-in Suspense support, preventing unnecessary re-renders and network requests.

Table of Contents

• Installation
• Quick Start
• Features
• Live Demo
• API Reference
  • useResource
  • mutate (⚠️ Experimental)
• Advanced Usage
• Best Practices
• TypeScript Support
• Comparison with Other Solutions
• Requirements

Features

• 🎯 Smart Caching - Automatic request deduplication and intelligent cache management
• ⚡ React Suspense - First-class Suspense support for elegant loading states
• 🔄 Automatic Revalidation - Configurable TTL-based cache invalidation
• 🎨 Flexible Loading States - isLoading and isValidating for fine-grained UI control
• 🔒 Type-safe - Full TypeScript support with automatic type inference
• 🪶 Lightweight - Minimal dependencies, small bundle size
• 🚀 Performance Optimized - Components sharing the same key share data and state

Live Demo

Explore an interactive demo showcasing some of the features:

• Suspense Mode - React Suspense integration with loading fallbacks
• Error Handling - ErrorBoundary catching errors from failed fetches
• Optimistic Updates - Instant UI updates with mutate() and proper rollback
• Shared State - Multiple components sharing the same resource key
• Loading States - Fine-grained control with isLoading and isValidating

Run the demo locally:

cd example
pnpm install
pnpm dev

Installation

pnpm add @dmrk/use-resource

Quick Start

With Suspense (Recommended)

import { useResource } from '@dmrk/use-resource';

function User({ userId }: { userId: string }) {
  const { data } = useResource(`user-${userId}`, () =>
    fetch(`/api/users/${userId}`).then(res => res.json())
  );

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

function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <User userId="123" />
    </Suspense>
  );
}

Without Suspense

function User({ userId }: { userId: string }) {
  const { data, error, isLoading, refetch } = useResource(
    `user-${userId}`,
    () => fetch(`/api/users/${userId}`).then(res => res.json()),
    { suspense: false }
  );

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

  return (
    <div>
      <p>Hello, {data.name}!</p>
      <button onClick={refetch}>Refresh</button>
    </div>
  );
}

API Reference

useResource(key, fetcher, options?)

The main hook for fetching and caching data.

Parameters:

• key (string): Unique identifier for the resource. Components with the same key share cached data.
• fetcher (() => T | Promise): Function that returns data synchronously or asynchronously.
• options (optional):
  • suspense (boolean): Enable Suspense mode. Default: true
  • ttl (number): Time-to-live in seconds. Resource revalidates after expiration. Default: 60

Returns:

{
  data: T | undefined;           // The fetched data
  error: Error | undefined;      // Error if fetch failed
  isLoading: boolean;            // true during initial load (no data yet)
  isValidating: boolean;         // true during any fetch (initial or refetch)
  refetch: () => void;           // Manually trigger a refetch
}

State Behavior:

Status	isLoading	isValidating	data	Description
pending	✅ true	✅ true	❌ undefined	Initial fetch in progress
fulfilled	❌ false	❌ false	✅ available	Data loaded successfully
revalidating	❌ false	✅ true	✅ available	Refetching with stale data
rejected	❌ false	❌ false	❌ undefined	Fetch failed with error

Examples:

// Basic usage
const { data } = useResource('todos', fetchTodos);

// With TTL (revalidates every 5 minutes)
const { data } = useResource('user', fetchUser, { ttl: 300 });

// Without Suspense
const { data, isLoading, error } = useResource('posts', fetchPosts, {
  suspense: false,
});

// Synchronous fetcher
const { data } = useResource('config', () => ({
  theme: 'dark',
  language: 'en',
}));

mutate(key, data) ⚠️ Experimental

Warning: This API is experimental and may change in future versions.

Manually update cached data without refetching. Useful for optimistic updates.

Parameters:

• key (string): The resource key to update
• data (T): New data to set in cache

Returns:

• boolean: true if mutation succeeded, false if resource is currently pending/revalidating

Example:

import { mutate } from '@dmrk/use-resource';

function TodoList() {
  const { data: todos, refetch } = useResource('todos', fetchTodos, {
    suspense: false,
  });

  const addTodo = async (text: string) => {
    const newTodo = { id: Date.now(), text, completed: false };

    // Optimistically update UI
    mutate('todos', [...(todos || []), newTodo]);

    try {
      await fetch('/api/todos', {
        method: 'POST',
        body: JSON.stringify(newTodo),
      });
    } catch (error) {
      // Revert on error by refetching
      refetch();
    }
  };

  return (
    <div>
      {todos?.map(todo => (
        <TodoItem key={todo.id} todo={todo} />
      ))}
      <button onClick={() => addTodo('New task')}>Add</button>
    </div>
  );
}

Limitations:

• Cannot mutate resources that are currently pending or revalidating
• Does not trigger network requests (use refetch() for that)
• API may change in future versions

Advanced Usage

Shared State Between Components

Multiple components using the same key automatically share data and state:

function UserProfile() {
  const { data } = useResource('current-user', fetchCurrentUser);
  return <div>{data.name}</div>;
}

function UserAvatar() {
  const { data, refetch } = useResource('current-user', fetchCurrentUser);
  // ✅ Shares the same data as UserProfile
  // ✅ refetch() updates both components
  return <img src={data.avatar} onClick={refetch} />;
}

Conditional Fetching

function User({ userId }: { userId: string | null }) {
  const { data } = useResource(
    userId ? `user-${userId}` : 'no-user',
    userId ? () => fetchUser(userId) : () => null
  );

  if (!userId) return <div>No user selected</div>;
  return <div>{data.name}</div>;
}

Dependent Queries

function UserPosts({ userId }: { userId: string }) {
  const { data: user } = useResource(`user-${userId}`, () => fetchUser(userId));

  const { data: posts } = useResource(`posts-${user.id}`, () =>
    fetchUserPosts(user.id)
  );

  return <PostList posts={posts} />;
}

Error Boundaries with Suspense

class ErrorBoundary extends React.Component {
  state = { hasError: false, error: null };

  static getDerivedStateFromError(error: Error) {
    return { hasError: true, error };
  }

  render() {
    if (this.state.hasError) {
      return <div>Error: {this.state.error.message}</div>;
    }
    return this.props.children;
  }
}

function App() {
  return (
    <ErrorBoundary>
      <Suspense fallback={<div>Loading...</div>}>
        <User userId="123" />
      </Suspense>
    </ErrorBoundary>
  );
}

Best Practices

✅ Use Descriptive Keys

// Good: Descriptive, unique keys
useResource(`user-${userId}`, () => fetchUser(userId));
useResource(`posts-${userId}-page-${page}`, () => fetchPosts(userId, page));

// Bad: Generic keys
useResource('data', fetchData);

✅ Set Appropriate TTL

// Frequently changing data: short TTL
useResource('stock-price', fetchStockPrice, { ttl: 10 });

// Rarely changing data: long TTL
useResource('countries', fetchCountries, { ttl: 3600 });

// Static data: no TTL
useResource('app-config', fetchConfig);

✅ Handle Loading and Error States

// With Suspense: wrap in Suspense and ErrorBoundary
<ErrorBoundary>
  <Suspense fallback={<Spinner />}>
    <DataComponent />
  </Suspense>
</ErrorBoundary>;

// Without Suspense: check isLoading and error
const { data, isLoading, error } = useResource('data', fetchData, {
  suspense: false,
});
if (isLoading) return <Spinner />;
if (error) return <ErrorMessage error={error} />;

⚠️ Avoid Dynamic Keys Without Memoization

// Bad: Creates new key on every render
useResource(`user-${Date.now()}`, fetchUser);

// Good: Stable key
const key = useMemo(() => `user-${userId}`, [userId]);
useResource(key, fetchUser);

TypeScript Support

Automatic type inference - TypeScript automatically infers the return type from your fetcher function:

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

async function fetchUser(userId: string): Promise<User> {
  const res = await fetch(`/api/users/${userId}`);
  return res.json();
}

function UserProfile({ userId }: { userId: string }) {
  // ✅ TypeScript automatically infers data as User from fetchUser's return type
  // No need to pass generic <User>!
  const { data, error, refetch } = useResource(
    `user-${userId}`,
    () => fetchUser(userId),
    { suspense: false }
  );

  if (!data) return null;

  // ✅ TypeScript knows data.name, data.email exist
  return (
    <div>
      <h1>{data.name}</h1>
      <p>{data.email}</p>
    </div>
  );
}

// You can also use inline async functions with explicit return types
function PostList() {
  const { data } = useResource('posts', async (): Promise<Post[]> => {
    const res = await fetch('/api/posts');
    return res.json();
  });

  // ✅ data is automatically typed as Post[]
  return (
    <div>
      {data.map(post => (
        <PostItem key={post.id} post={post} />
      ))}
    </div>
  );
}

// Only pass generic when you can't infer the type (rare cases)
const { data } = useResource<User>(
  'user',
  () => fetch('/api/user').then(r => r.json()) // r.json() returns any
);

Comparison with Other Solutions

Note: use-resource is a minimal, experimental library built for exploration. It intentionally lacks many advanced features found in mature libraries. Choose based on your project's needs.

vs SWR

Feature	SWR	use-resource
Bundle Size	~5KB	~2KB
Suspense Support	✅ Optional	✅ Default
TypeScript Inference	Good	Excellent
API Complexity	Moderate	Minimal
Community & Ecosystem	Large, mature	Experimental
Advanced Features	Middleware, focus revalidation, optimistic UI, mutations	Basic caching only
Sync Fetchers	❌	✅
Setup Required	None	None
Production Ready	✅	⚠️ Experimental

vs React Query

Feature	React Query	use-resource
Bundle Size	~13KB	~2KB
Suspense Support	✅ Via hooks	✅ Default
TypeScript Inference	Good	Excellent
API Complexity	Complex (powerful)	Minimal (limited)
Community & Ecosystem	Largest	Experimental
Advanced Features	Devtools, infinite queries, mutations, prefetching, query invalidation, retry logic, pagination	Basic caching only
Setup Required	QueryClient provider	None
Learning Curve	Steeper	Minimal
Production Ready	✅	⚠️ Experimental

vs Manual useEffect + useState

Feature	useEffect + useState	use-resource
Bundle Size	0 (built-in)	~2KB
Code Required	High boilerplate	One hook call
Caching	Manual	Automatic
Request Deduplication	Manual	Automatic
Race Conditions	Must handle manually	Handled automatically
Loading States	Manual	Automatic
Suspense Support	Manual integration	Built-in
Type Safety	Manual typing	Inferred

Requirements

• React 18.0.0 or higher (for Suspense support)

License

ISC

Contributing

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

Author

dmrk