Installation
Complete guide to installing and configuring @igniter-js/caller. Covers all package managers, TypeScript setup, optional dependencies, and environment configuration.
Prerequisites
Before installing Caller, ensure your environment meets these requirements:
| Requirement | Minimum | Notes |
|---|---|---|
| Node.js | ≥ 18.0 | Native fetch support required |
| Bun | ≥ 1.0 | Alternative runtime |
| Deno | ≥ 1.40 | Alternative runtime |
| TypeScript | ≥ 5.0 | Recommended for full type safety |
Caller works in any environment where fetch is available: Node.js 18+, Bun, Deno, Cloudflare Workers, Vercel Edge, and modern browsers.
Install the Package
npm install @igniter-js/callerpnpm add @igniter-js/calleryarn add @igniter-js/callerbun add @igniter-js/caller@igniter-js/common is installed automatically as a peer dependency.
Optional Dependencies
Caller has a modular architecture — install only what you need:
Schema Validation
To use schema-based type inference and runtime validation, install a StandardSchemaV1-compatible library:
npm install zodpnpm add zodyarn add zodbun add zodAny StandardSchemaV1 library works
While the examples use Zod, Caller supports any library that implements the StandardSchemaV1 interface — including Valibot, ArkType, and custom schemas.
Telemetry
For observability features (request tracing, metrics, event emission):
npm install @igniter-js/telemetrypnpm add @igniter-js/telemetryyarn add @igniter-js/telemetrybun add @igniter-js/telemetryReact Integration
For React hooks (useQuery, useMutate), install React alongside Caller:
npm install react @igniter-js/callerpnpm add react @igniter-js/calleryarn add react @igniter-js/callerbun add react @igniter-js/callerReact 18+ required
The React client (@igniter-js/caller/client) requires React 18 or later. It uses hooks and the useId API.
Create Your First Client
After installation, create a configured API client:
import { IgniterCaller } from '@igniter-js/caller';
export const api = IgniterCaller.create()
.withBaseUrl(process.env.API_URL || 'http://localhost:3000')
.withHeaders({
'Authorization': `Bearer ${process.env.API_TOKEN}`,
'Content-Type': 'application/json',
})
.build();Zero Configuration Required
Caller works out of the box with no configuration. If you just need to make HTTP requests, IgniterCaller.create().build() is all you need.
Configuration Options
The IgniterCallerBuilder exposes a fluent, immutable API for configuring your client:
| Method | Purpose |
|---|---|
.withBaseUrl(url) | Prefix for all request URLs |
.withHeaders(headers) | Default headers merged into every request |
.withCookies(cookies) | Default cookies (serialized as Cookie header) |
.withLogger(logger) | Logger instance for request lifecycle events |
.withTelemetry(telemetry) | Telemetry manager for observability |
.withSchemas(schemas, options?) | Schema-based type safety and runtime validation |
.withRequestInterceptor(fn) | Transform requests before they are sent |
.withResponseInterceptor(fn) | Transform responses after they are received |
.withStore(adapter, options?) | Persistent store for caching (Redis, etc.) |
.withMock(config) | Enable mock mode for testing |
.build() | Finalize configuration and return the manager |
Every with* method returns a new builder instance — the builder is fully immutable. This means you can safely create multiple derived clients from a base configuration:
// Base client with shared auth
const base = IgniterCaller.create()
.withHeaders({ 'Authorization': `Bearer ${token}` });
// Public API client
const api = base.withBaseUrl('https://api.example.com').build();
// Admin API client (different base URL, same auth)
const admin = base.withBaseUrl('https://admin.example.com').build();Project Structure
For larger projects, we recommend organizing your API configuration:
src/
├── lib/
│ ├── api.ts # Core API client setup
│ └── schemas/
│ ├── index.ts # Schema registry
│ ├── users.ts # User-related schemas
│ └── products.ts # Product-related schemas
├── callers/
│ └── facebook/ # CLI-generated clients
│ ├── index.ts
│ └── schema.ts
└── features/
└── users/
└── api.ts # Feature-specific API helpersMonorepo Setup
In a monorepo with shared packages:
import { IgniterCaller, IgniterCallerSchema } from '@igniter-js/caller';
import { sharedSchemas } from '@my-org/schemas';
export const api = IgniterCaller.create()
.withBaseUrl(process.env.API_URL!)
.withSchemas(sharedSchemas, { mode: 'strict' })
.withRequestInterceptor(async (config) => ({
...config,
headers: {
...config.headers,
'X-Client-Id': 'web',
},
}))
.build();Environment Configuration
Caller doesn't require any environment variables by default, but here's a typical setup:
API_URL=https://api.example.com/v1
API_TOKEN=your-api-tokenimport { IgniterCaller } from '@igniter-js/caller';
export const api = IgniterCaller.create()
.withBaseUrl(process.env.API_URL!)
.withHeaders({
'Authorization': `Bearer ${process.env.API_TOKEN}`,
})
.build();Next.js Configuration
For Next.js applications, use the appropriate variable prefix:
NEXT_PUBLIC_API_URL=https://api.example.com/v1export const api = IgniterCaller.create()
.withBaseUrl(process.env.NEXT_PUBLIC_API_URL || '/api')
.build();Server vs Client
In Next.js App Router, you can use Caller in both Server Components (direct .execute()) and Client Components (via the React provider). Server-side usage doesn't need NEXT_PUBLIC_ prefix — use regular process.env variables.
TypeScript Configuration
Caller requires no special TypeScript configuration. The default strict: true setting provides the best type inference experience:
{
"compilerOptions": {
"strict": true,
"target": "ES2022",
"module": "ESNext",
"moduleResolution": "bundler"
}
}Path Aliases
If you use path aliases, ensure they resolve correctly:
{
"compilerOptions": {
"paths": {
"@/*": ["./src/*"]
}
}
}Common Issues
Next Steps
Quick Start
Make your first type-safe HTTP request with Caller in under 2 minutes. Step-by-step guide covering installation, client creation, and common patterns.
Comparison
How Caller compares to Axios, ky, ofetch, and native fetch. Understand the trade-offs and choose the right HTTP client for your project.