[](https://www.npmjs.com/package/next-unified-query)
[](https://www.npmjs.com/package/next-unified-query)
[](https://packagephobia.com/result?p=next-unified-query)
[](https://www.typescriptlang.org/)
[](LICENSE)
**The Modern HTTP Client for React - Unified Config, Type-Safe, Performance Optimized**
*Combines the best of TanStack Query and fetch with unmatched TypeScript support and performance optimizations*
### 📚 **Documentation**
[🚀 **Quick Start**](#-quick-start-30-seconds-to-running) • [📖 **API Reference**](https://github.com/newExpand/next-unified-query/blob/main/API.md) • [🎓 **User Guide**](https://github.com/newExpand/next-unified-query/blob/main/USER_GUIDE.md) • [⚡ **Performance**](https://github.com/newExpand/next-unified-query/blob/main/PERFORMANCE.md) • [💬 **GitHub**](https://github.com/newExpand/next-unified-query)
---
## ✨ **Why Next Unified Query?**
Stop fighting with scattered configurations, endless re-renders, and type safety issues. Next Unified Query is built for modern React applications that demand **performance**, **type safety**, and **developer experience**.
### 🔥 **Problems We Solve**
| **Common Pain Points** | **Next Unified Query Solution** |
|---|---|
| 🔄 Unnecessary re-renders hurting performance | **Optimized re-rendering** with selective subscriptions |
| 🔧 Scattered baseURL configs across app | **Unified configuration** - set once, works everywhere |
| 🐛 Runtime errors from wrong HTTP methods | **Compile-time safety** with method-specific types |
| 📦 Large bundle sizes impacting load times | **~26KB gzipped** - optimized and tree-shakeable |
| 🌐 Complex SSR setup and hydration issues | **First-class Next.js support** with zero config |
| 🤯 Verbose boilerplate for simple requests | **Global functions** for direct API calls |
### 💡 **Unique Advantages**
- **🎯 Set It Once, Use Everywhere**: Configure baseURL, headers, and interceptors once - they work across `useQuery`, `useMutation`, and global functions
- **🛡️ Compile-Time HTTP Safety**: `useQuery` only allows GET/HEAD, `useMutation` prevents GET - catch errors before runtime
- **⚡ Performance by Default**: Optimized re-rendering that only updates when data you actually use changes
- **🔧 Factory Patterns**: Define type-safe, reusable API definitions with full TypeScript inference
- **🌐 SSR-First**: Built for Next.js with seamless server-side rendering and hydration
- **🆕 Environment-Specific Interceptors**: Separate client/server interceptors without `typeof window` checks
- **🎭 React 18+ Features** *(v0.2.0+)*: Built-in Error Boundary, Suspense support, and global default options
## 🚀 **Quick Start** *(30 seconds to running)*
### Installation
```bash
npm install next-unified-query
# or
yarn add next-unified-query
# or
pnpm add next-unified-query
```
**✨ Includes popular libraries built-in**:
- **Zod v4** for schema validation (no separate install needed!)
- **es-toolkit** for high-performance utility functions
- **quick-lru** for optimized caching
> 📦 **Package Size**: ~119KB publish size. Install size is larger (~6.6MB) because we include Zod v4 for type-safe validation out of the box. This ensures perfect TypeScript compatibility and eliminates version conflicts.
### Basic Setup
```tsx
// app/query-config.ts - Shared configuration
import type { QueryClientOptions } from 'next-unified-query';
export const queryConfig: QueryClientOptions = {
baseURL: 'https://jsonplaceholder.typicode.com',
timeout: 10000,
headers: {
'Content-Type': 'application/json',
},
// 🆕 Environment-specific interceptors (v0.2.0+)
interceptors: {
// Runs in all environments
request: (config) => {
config.headers['X-App-Version'] = '1.0.0';
return config;
}
},
clientInterceptors: {
// Client-only (browser) - direct access to localStorage, window, etc.
request: (config) => {
const token = localStorage.getItem('token'); // No typeof check needed!
if (token) {
config.headers.Authorization = `Bearer ${token}`;
}
return config;
},
error: (error) => {
if (error.response?.status === 401) {
localStorage.removeItem('token');
window.location.href = '/login'; // Direct window access!
}
return Promise.reject(error);
}
},
serverInterceptors: {
// Server-only (Node.js) - access to process.env, server-side logging
request: (config) => {
config.headers['X-Server-Region'] = process.env.REGION;
return config;
}
}
};
```
```tsx
// app/layout.tsx - Configure for SSR
import { configureQueryClient } from 'next-unified-query';
import { queryConfig } from './query-config';
import { Providers } from './providers';
// Configure for both SSR and client
configureQueryClient(queryConfig);
export default function RootLayout({ children }) {
return (
{children}
);
}
```
```tsx
// app/providers.tsx - Client Component
'use client';
import { QueryClientProvider } from 'next-unified-query/react';
import { queryConfig } from './query-config';
export function Providers({ children }) {
return (
{children}
);
}
```
### Your First Query *(Now baseURL works everywhere!)*
```tsx
// app/users/page.tsx
import { useQuery, useMutation } from 'next-unified-query/react';
import { get, post } from 'next-unified-query';
export default function UsersPage() {
// ✅ All use the same baseURL automatically
const { data, isLoading } = useQuery({
cacheKey: ['users'],
url: '/users' // → https://jsonplaceholder.typicode.com/users
});
const createUser = useMutation({
url: '/users', // → https://jsonplaceholder.typicode.com/users
method: 'POST'
});
// ✅ Even global functions use the same config
const handleExport = async () => {
const csv = await get('/users/export'); // → same baseURL!
};
if (isLoading) return
Loading...
;
return (
Users ({data?.length})
{data?.map(user => (
{user.name}
))}
);
}
```
**🎉 That's it!** One configuration, works everywhere. No more scattered baseURL configs!
---
## 🌟 **Key Features That Set Us Apart**
### 🔧 **Unified Configuration System**
*Configure once, use everywhere - the way it should be*
```tsx
// ✅ Next Unified Query - ONE configuration in Provider
{
config.headers['Authorization'] = getToken();
return config;
}
}
}}>
{/* Now ALL these work with the same config: */}
{/* useQuery({ url: '/users' }) ✅ Auto baseURL */}
{/* useMutation({ url: '/posts' }) ✅ Auto baseURL */}
{/* await post('/analytics', data) ✅ Auto baseURL */}
```
**Traditional approaches often require:**
- Multiple configuration files and instances
- Separate HTTP client setup
- Manual coordination between different libraries
- Complex integration and maintenance
### 🛡️ **Compile-Time HTTP Method Safety**
*Catch API mistakes before they hit production*
```tsx
// ✅ Type-safe by design
const { data } = useQuery({
cacheKey: ['users'],
url: '/users' // ✅ Only GET/HEAD allowed - perfect for data fetching
});
const createUser = useMutation({
url: '/users',
method: 'POST' // ✅ POST/PUT/DELETE/PATCH allowed - perfect for mutations
});
// ❌ This won't even compile!
const badQuery = useQuery({
url: '/users',
method: 'POST' // 🚨 TypeScript Error: useQuery doesn't allow POST
});
```
**Why this matters**: Prevents accidental cache pollution and clarifies intent.
### 🏭 **Factory Pattern for Scalable APIs**
*Type-safe, reusable API definitions that scale with your team*
```tsx
// ✨ Import Zod directly - no separate installation needed!
import { createQueryFactory, createMutationFactory, z } from 'next-unified-query';
// Define once, use everywhere with full type safety
const userQueries = createQueryFactory({
list: {
cacheKey: () => ['users'] as const,
url: () => '/users',
schema: z.array(userSchema) // Automatic TypeScript inference!
},
get: {
cacheKey: (id: number) => ['users', id] as const,
url: (id: number) => `/users/${id}`,
schema: userSchema
}
});
const userMutations = createMutationFactory({
create: {
url: () => '/users',
method: 'POST',
requestSchema: createUserSchema,
responseSchema: userSchema
}
});
// Use with perfect TypeScript support
const { data } = useQuery(userQueries.list); // data is User[] ✨
const { data: user } = useQuery(userQueries.get, { params: { id: 1 } }); // user is User ✨
const createMutation = useMutation(userMutations.create);
```
### ⚡ **Advanced Performance Optimizations**
*Built on top of query library best practices with additional enhancements*
```tsx
// ✅ Selective subscriptions for optimal performance
function UserProfile({ userId }) {
const { data: userName } = useQuery({
cacheKey: ['user', userId],
url: `/users/${userId}`,
select: (user) => user.name // ✨ Only re-render on name changes
});
return
{userName}
;
}
// ✅ PLUS: Unified configuration benefits
// - No need to manage multiple HTTP client instances
// - Automatic baseURL application reduces config errors
// - Type-safe HTTP methods prevent cache pollution
// - Global functions share the same optimized setup
// Example: All these benefit from the same performance optimizations
const { data } = useQuery({ url: '/users' }); // Optimized rendering
const mutation = useMutation({ url: '/users' }); // Prevents GET usage
const response = await get('/users'); // Same interceptors
```
### 🌐 **First-Class SSR Support**
*Zero-config server-side rendering that just works*
```tsx
// app/users/[id]/page.tsx - Next.js App Router
import { ssrPrefetch } from 'next-unified-query';
import { HydrationBoundary } from 'next-unified-query/react';
import { userQueries } from '@/lib/queries';
export default async function UserPage({ params }) {
// ✅ Server-side prefetching uses config from configureQueryClient()
// No need to pass config - it's already configured globally!
const dehydratedState = await ssrPrefetch([
[userQueries.get, { id: params.id }],
[userQueries.posts, { userId: params.id }]
]);
return (
);
}
function UserDetail({ userId }) {
// ✅ Uses prefetched data immediately, no loading state!
const { data } = useQuery(userQueries.get, { params: { id: userId } });
return
{data?.name}
; // Instant render! ⚡
}
```
### 🛡️ **Built-in Error Boundary Support** *(v0.2.0+)*
*Graceful error handling with zero configuration*
```tsx
// ✅ Wrap your app with Error Boundary
import { QueryErrorBoundary } from 'next-unified-query/react';
function App() {
return (
(
Something went wrong!
{error.message}
)}
onError={(error, errorInfo) => {
// Log to error reporting service
console.error('Error caught:', error, errorInfo);
}}
>
);
}
// ✅ Use with hooks - errors automatically bubble up
function UserProfile() {
const { data } = useQuery({
url: '/users/1',
throwOnError: true // Throw to Error Boundary on error
});
const mutation = useMutation({
url: '/users',
method: 'POST',
throwOnError: (error) => error.response?.status >= 500 // Conditional throwing
});
return
{data?.name}
;
}
// ⚠️ Important: When using throwOnError: true, make sure your component is wrapped
// with an Error Boundary. Without it, errors will crash your application.
// In development mode, you'll see a warning in the console if an Error Boundary is missing.
```
### 🎭 **React Suspense Integration** *(v0.2.0+)*
*Modern loading states with concurrent rendering support*
```tsx
// ✅ Enable Suspense mode for declarative loading states
import { Suspense } from 'react';
function UserList() {
const { data } = useQuery({
url: '/users',
suspense: true // Enable Suspense mode
});
// No loading state needed - Suspense handles it!
return (