Cliente de API
O Cliente de API do Igniter fornece uma maneira perfeita de interagir com sua API backend a partir de suas aplicações frontend. Ele oferece segurança total de tipos, tratamento automático de erros e integração com hooks populares do React para busca de dados e mutações.
Configurando o Cliente de API
O primeiro passo é criar seu cliente de API conectando-o ao seu roteador Igniter:
// src/igniter.client.ts
import { createIgniterClient, useIgniterQueryClient } from '@igniter-js/core/client';
import { AppRouter } from './igniter.router';
/**
* Client for Igniter
*
* This client is used to fetch data on the client-side
* It uses the createIgniterClient function to create a client instance
*/
export const api = createIgniterClient(AppRouter);
/**
* Query client for Igniter
*
* This client provides access to the Igniter query functions
* and handles data fetching with respect to the application router.
* It will enable the necessary hooks for query management.
*/
export const useQueryClient = useIgniterQueryClient<typeof AppRouter>;
Integrando com React
Para usar o cliente de API em sua aplicação React, envolva seu aplicativo com o provedor Igniter:
// app/providers.tsx
import { IgniterProvider } from '@igniter-js/core/client'
export function Providers({ children }: { children: React.ReactNode }) {
return (
<IgniterProvider>
{children}
</IgniterProvider>
)
}
Fazendo Chamadas de API
Usando Queries (Requisições GET)
O hook useQuery fornece uma maneira poderosa de buscar dados com cache automático e revalidação:
import { api } from '@/igniter.client'
function UsersList() {
const { data: users, loading, error, refetch } = api.users.list.useQuery({
// Optional configuration
initialData: [], // Initial data while loading
staleTime: 1000 * 60, // Data stays fresh for 1 minute
refetchInterval: 1000 * 30, // Refetch every 30 seconds
refetchOnWindowFocus: true, // Refetch when window regains focus
refetchOnMount: true, // Refetch when component mounts
refetchOnReconnect: true, // Refetch when reconnecting
onLoading: (isLoading) => console.log('Loading:', isLoading),
onRequest: (response) => console.log('Data received:', response)
})
if (loading) return <div>Loading...</div>
if (error) return <div>Error: {error.message}</div>
return (
<div>
<button onClick={() => refetch()}>Refresh</button>
{users.map(user => (
<div key={user.id}>{user.name}</div>
))}
</div>
)
}
Usando Mutations (Requisições POST, PUT, DELETE)
O hook useMutation lida com modificações de dados com estados de carregamento e tratamento de erros:
function CreateUserForm() {
const { mutate, loading, error } = api.users.create.useMutation({
// Optional configuration
defaultValues: { name: '', email: '' },
onLoading: (isLoading) => console.log('Loading:', isLoading),
onRequest: (response) => console.log('Created user:', response)
})
const handleSubmit = async (e: React.FormEvent) => {
e.preventDefault()
try {
await mutate({
body: {
name: 'John Doe',
email: 'john@example.com'
}
})
// Handle success
} catch (error) {
// Handle error
}
}
return (
<form onSubmit={handleSubmit}>
{/* Form fields */}
<button type="submit" disabled={loading}>
{loading ? 'Creating...' : 'Create User'}
</button>
{error && <div>Error: {error.message}</div>}
</form>
)
}
Gerenciando Cache
Você pode invalidar queries manualmente ou automaticamente após mutações:
function AdminPanel() {
const queryClient = useQueryClient()
// Invalidate specific queries
const invalidateUsers = () => {
queryClient.invalidate('users.list')
}
// Invalidate multiple queries
const invalidateAll = () => {
queryClient.invalidate([
'users.list',
'users.get'
])
}
return (
<button onClick={invalidateUsers}>
Refresh Users
</button>
)
}
Segurança de Tipos
O Cliente de API do Igniter fornece inferência completa de tipos para sua API:
// All these types are automatically inferred
import { InferOutput, InferInput } from '@igniter-js/core/client'
type User = InferOutput<typeof api.users.get>
type CreateUserInput = InferInput<typeof api.users.create>
// TypeScript will show errors for invalid inputs
api.users.create.useMutation({
onRequest: (data) => {
data.id // ✅ Typed as string
data.invalid // ❌ TypeScript error
}
})
Uso no Lado do Servidor
Integração com o App Router do Next.js
Você pode usar chamadas diretas ao servidor com Componentes de Servidor React:
// app/users/page.tsx
import { api } from '@/igniter.client'
export default async function UsersPage() {
const users = await api.users.list.call()
return (
<div>
{users.map(user => (
<div key={user.id}>{user.name}</div>
))}
</div>
)
}
Ações do Servidor
// app/users/actions.ts
'use server'
import { api } from '@/igniter.client'
export async function createUser(formData: FormData) {
const name = formData.get('name') as string
const email = formData.get('email') as string
return api.users.create.call({
body: { name, email }
})
}
// app/users/create-form.tsx
export function CreateUserForm() {
return (
<form action={createUser}>
<input name="name" />
<input name="email" type="email" />
<button type="submit">Create User</button>
</form>
)
}
Tratamento de Erros
O cliente de API fornece recursos robustos de tratamento de erros:
function UserProfile() {
const { data, error, retry } = api.users.get.useQuery({
onError: (error) => {
console.error('Failed to fetch user:', error)
},
retry: 3, // Retry failed requests
retryDelay: 1000, // Wait 1 second between retries
})
if (error) {
return (
<div>
Error loading profile
<button onClick={retry}>Try Again</button>
</div>
)
}
return <div>{/* User profile content */}</div>
}
Testes
O cliente de API pode ser usado em testes para verificar a funcionalidade da sua API:
import { api } from '@/igniter.client'
describe('User API', () => {
it('should create a user', async () => {
const result = await api.users.create.call({
body: {
name: 'Test User',
email: 'test@example.com'
}
})
expect(result.status).toBe(201)
expect(result.data).toHaveProperty('id')
})
})
Ao usar o Cliente de API do Igniter, você obtém uma maneira totalmente segura em termos de tipos para interagir com sua API backend, com suporte integrado para cache, tratamento de erros e integração com React.
Acelere seu desenvolvimento
Construa aplicações SaaS completas em minutos com nosso boilerplate moderno. Autenticação, pagamentos, gerenciamento de usuários e muito mais!
Conheça o SaaS Boilerplate