Configuration

Learn how to configure qortex for optimal performance and behavior. Global defaults, per-query options, and best practices.

Configuration Options

Global Defaults

Set default configuration for all queries

import { setDefaultConfig, registerFetcher, setQueryData, getQueryData, invalidateQuery, dangerClearCache } from "qortex-core";

// Set global defaults
setDefaultConfig({
  staleTime: 5 * 60 * 1000, // 5 minutes
  refetchOnSubscribe: "stale",
  throttleTime: 100,
  usePreviousDataOnError: false,
  usePlaceholderOnError: false,
  equalityFn: shallowEqual
});

Options:

staleTime(number)default: 0Time before data is considered stale (ms)
refetchOnSubscribe("stale" | "always" | false)default: "stale"When to refetch on subscription
throttleTime(number)default: 50Throttle time for duplicate requests (ms)
usePreviousDataOnError(boolean)default: falseKeep previous data when errors occur
usePlaceholderOnError(boolean)default: falseUse placeholder data on errors
equalityFn(EqualityFn<any>)default: Object.isFunction to compare data equality

Per-Query Configuration

Override defaults for specific queries

// Register fetcher with custom options
registerFetcher(["live-data"], {
  fetcher: async () => {
    const response = await fetch("/api/live-data");
    return response.json();
  },
  staleTime: 0, // Always stale for live data
  placeholderData: { value: 0, timestamp: Date.now() }
});

// Use with additional options
const { data } = useQuery(["live-data"], {
  refetchOnSubscribe: "always", // Override global default
  enabled: isOnline // Conditional fetching
});

Options:

staleTime(number)Override global stale time
placeholderData(T)Data to show while loading
equalityFn(EqualityFn<T>)Custom equality function

Cache Management

Control caching behavior and data updates

// Manual data updates
setQueryData(["todos"], newTodos);

// Get current data
const currentTodos = getQueryData(["todos"]);

// Clear all cached data (testing only)
dangerClearCache();

Options:

setQueryData(function)Manually update query data
getQueryData(function)Get current query data
dangerClearCache(function)⚠️ Clear all cached data (testing only)

Error Handling

Configure error handling and retry behavior

// Global error handling
setDefaultConfig({
  usePreviousDataOnError: true, // Keep previous data
  usePlaceholderOnError: false  // Don't use placeholder on error
});

// Per-query error handling
registerFetcher(["critical-data"], {
  fetcher: async () => {
    const response = await fetch("/api/critical-data");
    if (!response.ok) throw new Error('Failed to fetch critical data');
    return response.json();
  },
  placeholderData: { status: 'loading' },
  usePlaceholderOnError: true // Use placeholder on error
});

// In component
const { data, error, refetch } = useQuery(["critical-data"], {
  usePreviousDataOnError: false // Override for this query
});

Options:

usePreviousDataOnError(boolean)Keep previous data when errors occur
usePlaceholderOnError(boolean)Use placeholder data on errors
placeholderData(T)Fallback data for loading/error states

Best Practices

Stale Time Configuration

Set appropriate stale times based on data characteristics

TypeValueReason
User Profile5 * 60 * 1000Changes infrequently
Live Data0Always needs fresh data
Static Content30 * 60 * 1000Rarely changes
Search Results2 * 60 * 1000Moderate update frequency

Throttle Time Optimization

Balance between responsiveness and performance

TypeValueReason
User Input300Debounce user interactions
API Calls100Prevent duplicate requests
Real-time50Minimal delay for live data

Placeholder Data Strategy

Provide meaningful fallback data for better UX

TypeValueReason
Lists[]Show empty state while loading
Objects{}Prevent undefined errors
Numbers0Provide default numeric value

Performance Tips

✅ Do

  • • Set appropriate stale times for your data
  • • Use placeholder data to prevent layout shifts
  • • Configure throttle time to prevent duplicate requests
  • • Use equality functions for complex data structures
  • • Enable previous data on error for better UX

❌ Don't

  • • Set stale time too low for static data
  • • Ignore error handling configuration
  • • Use heavy equality functions unnecessarily
  • • Disable throttling for high-frequency updates
  • • Forget to provide placeholder data

Ready to Configure?

Now that you understand configuration options, explore more advanced features and patterns.