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 subscriptionthrottleTime
(number)default: 50Throttle time for duplicate requests (ms)usePreviousDataOnError
(boolean)default: falseKeep previous data when errors occurusePlaceholderOnError
(boolean)default: falseUse placeholder data on errorsequalityFn
(EqualityFn<any>)default: Object.isFunction to compare data equalityPer-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 timeplaceholderData
(T)Data to show while loadingequalityFn
(EqualityFn<T>)Custom equality functionCache 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 datagetQueryData
(function)Get current query datadangerClearCache
(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 occurusePlaceholderOnError
(boolean)Use placeholder data on errorsplaceholderData
(T)Fallback data for loading/error statesBest Practices
Stale Time Configuration
Set appropriate stale times based on data characteristics
Type | Value | Reason |
---|---|---|
User Profile | 5 * 60 * 1000 | Changes infrequently |
Live Data | 0 | Always needs fresh data |
Static Content | 30 * 60 * 1000 | Rarely changes |
Search Results | 2 * 60 * 1000 | Moderate update frequency |
Throttle Time Optimization
Balance between responsiveness and performance
Type | Value | Reason |
---|---|---|
User Input | 300 | Debounce user interactions |
API Calls | 100 | Prevent duplicate requests |
Real-time | 50 | Minimal delay for live data |
Placeholder Data Strategy
Provide meaningful fallback data for better UX
Type | Value | Reason |
---|---|---|
Lists | [] | Show empty state while loading |
Objects | {} | Prevent undefined errors |
Numbers | 0 | Provide 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.