Smart TV Query
Tiny, dependency-free query client with smart caching, request deduplication, and legacy TV support.
Key Features
Lightweight & Fast
Zero dependencies, tiny bundle size optimized for TV apps
Smart Caching
Configurable stale time and cache time for optimal performance
Request Deduplication
Automatic deduplication of identical requests
Legacy TV Support
XHR-based fetcher for maximum compatibility
React Hooks
useQuery, useMutation, and useInfiniteQuery hooks
Tree Shakeable
Import only what you need for minimal bundle size
Installation
Install the Smart TV Query package using your preferred package manager:
Quick Start
Get started with Smart TV Query in just a few steps:
import React from 'react';
import { QueryClient, QueryClientProvider, useQuery } from '@smart-tv/query';
// Create a query client
const queryClient = new QueryClient({
defaultOptions: {
staleTime: 5 * 60 * 1000, // 5 minutes
cacheTime: 10 * 60 * 1000, // 10 minutes
}
});
// Wrap your app with the provider
function App() {
return (
<QueryClientProvider client={queryClient}>
<Movies />
</QueryClientProvider>
);
}
// Use the query hook in your components
function Movies() {
const { data, error, status, refetch } = useQuery(
['movies'],
() => fetch('/api/movies').then(r => r.json())
);
if (status === 'loading') return <div>Loading...</div>;
if (status === 'error') return <div>Error: {error.message}</div>;
return (
<div>
<h1>Movies</h1>
<ul>
{data?.map(movie => (
<li key={movie.id}>{movie.title}</li>
))}
</ul>
<button onClick={() => refetch()}>Refresh</button>
</div>
);
}Legacy Smart TV Support
For maximum compatibility with older Smart TV platforms that don't support modern fetch API, Smart TV Query includes a powerful XHR-based fetcher.
Why XHR for Smart TVs?
- • Many older Smart TV platforms (2015-2018) don't support fetch API
- • XMLHttpRequest is universally supported across all TV browsers
- • Provides additional features like upload/download progress and timeout control
- • Better error handling for unreliable TV network connections
import { QueryClient, QueryClientProvider, useQuery, xhrFetcher, tvFetch } from '@smart-tv/query';
// Use xhrFetcher directly in query functions
function Movies() {
const { data, error, status } = useQuery(
['movies'],
() => xhrFetcher('/api/movies').then(response => response.json())
);
if (status === 'loading') return <div>Loading...</div>;
if (status === 'error') return <div>Error: {error.message}</div>;
return (
<div>
<h1>Movies ({data.length})</h1>
<ul>
{data?.map(movie => (
<li key={movie.id}>{movie.title}</li>
))}
</ul>
</div>
);
}
// Advanced XHR options for Smart TV optimization
const fetchMovieWithProgress = (id) => {
return xhrFetcher(`/api/movies/${id}`, {
method: 'GET',
timeout: 15000, // 15 second timeout for slow TV networks
responseType: 'json',
headers: {
'Accept': 'application/json',
'X-Device-Type': 'smart-tv'
},
onDownloadProgress: (loaded, total) => {
console.log(`Download progress: ${loaded}/${total}`);
}
});
};
// tvFetch is an alias for xhrFetcher
function StreamingContent() {
const { data } = useQuery(
['streaming-content'],
() => tvFetch('/api/streaming/content', {
timeout: 20000, // Longer timeout for content metadata
withCredentials: true, // Include credentials for authenticated endpoints
}).then(response => response.json())
);
return <div>{/* render streaming content */}</div>;
}Core API
Essential hooks and utilities
QueryClient
The central client that manages cache, configurations, and query lifecycle.
new QueryClient({ staleTime: 5min })useQuery
Hook for fetching and caching data with automatic background updates.
useQuery(['key'], fetcher)useMutation
Hook for creating, updating, or deleting data with optimistic updates.
useMutation(mutationFn, options)useInfiniteQuery
Hook for implementing infinite scrolling and pagination patterns.
useInfiniteQuery(['key'], fetcher)Why Smart TV Query?
| Feature | Smart TV Query | React Query | SWR |
|---|---|---|---|
| Bundle Size | ~5KB | ~45KB | ~25KB |
| Dependencies | Zero | Multiple | Few |
| TV Optimized | ✓ Yes | ○ No | ○ No |
| Legacy TV Support | ✓ XHR Fetcher | ✗ Fetch only | ✗ Fetch only |
| Progress Tracking | ✓ Upload/Download | ○ Limited | ○ Limited |
| TypeScript | ✓ Built-in | ✓ Built-in | ✓ Built-in |
| Caching | ✓ Simple | ✓ Advanced | ✓ Simple |
Documentation
Explore detailed guides and API references