urql GraphQL Client

urql is a modular collection of packages. Most users interact with the library through either framework bindings (e.g., React, Preact, Svelte) or exchange packages (e.g., graphcache, retry, auth).

Most packages depend on or utilize utilities and types from the @urql/core package.

Note: Detailed API documentation is now provided via TSDocs directly within your editor (via the TypeScript Language Server) for all published packages.

urql is a highly customizable and versatile GraphQL client designed to grow with your application. It prioritizes usability for newcomers while remaining extensible for complex, dynamic applications.

Key features include:

• Document Caching: Suitable for content-heavy pages.
• Normalized Caching: Provided via the @urql/exchange-graphcache addon for dynamic, data-heavy applications.
• Extensibility: The core logic resides in @urql/core, which can be extended using addon packages called Exchanges.

urql is a highly customizable and versatile GraphQL client designed to scale from simple projects to complex applications.

Key features include:

• Framework Support: Provides helpers for React, Preact, Vue, Solid, and Svelte.
• Extensibility: Behavior is fully customizable via a system of "exchanges."
• Caching: Includes logical default behavior and document caching, with support for normalized caching via @urql/exchange-graphcache.
• Debugging: Supports easy debugging through urql devtools browser extensions.

The urql React example demonstrates how to integrate urql bindings into a React application. The key components of the example are:

• Client Setup: The urql bindings and the client configuration are located in src/App.jsx.
• Data Fetching: A practical example of querying data (specifically Pokémon) is implemented in src/PokemonList.jsx.

Use @urql/solid-start when building applications with SolidStart that require Server-Side Rendering (SSR), streaming responses, and progressive enhancement. It integrates URQL with SolidStart's primitives like query(), action(), and the router's caching system.

Key Features:

• Automatic SSR: Queries run on the server and stream to the client.
• Request Deduplication: Leverages SolidStart's query caching.
• Progressive Enhancement: Mutations use SolidStart actions, allowing them to work without JavaScript.
• Fine-grained Reactivity: Native support for SolidJS Suspense boundaries.

urql is designed to be highly extensible via Exchanges, which allow for customization at both the network level and the cache/control flow level. This distinguishes it from Apollo and Relay, which primarily focus on network-level extensibility (Links/Network Layers).

Key feature advantages of urql include:

• Extensibility: Caching logic is abstracted into exchanges, making it easy to swap caching strategies.
• Bundle Size: Significantly smaller base bundle size (~10kB) compared to Apollo (~50kB) or Relay (~45kB).
• First-class support for features like Focus Refetching (@urql/exchange-refocus), Stale Time Configuration (@urql/exchange-request-policy), and Easy Authentication (@urql/exchange-auth).
• Live Queries: Supported via Incremental Delivery.
• File Uploads: Supported natively.

next-urql provides convenience utilities to integrate urql with Next.js, specifically optimized for Server-Side Rendering (SSR) patterns. It helps manage the handoff of GraphQL state from the server to the client to ensure consistent data fetching and hydration.

For detailed implementation guides, refer to the official documentation on Server-Side Rendering with Next.js.

Graphcache provides several advanced capabilities beyond standard document caching:

• Fully reactive, normalized caching: Automatically updates related data across queries, mutations, and subscriptions.
• Custom cache resolvers: Allows formatting data, implementing pagination, or handling cache redirects.
• Subscription and Mutation updates: Enables reactive cache updates via update functions without requiring full query refetches.
• Optimistic mutation updates: Allows the UI to render expected data immediately before a mutation succeeds.
• Opt-in schema awareness: Uses your GraphQL schema to resolve partial data and handle interfaces/enums correctly.
• Offline support: Supports persisting and rehydrating the entire cache state for offline use.
• Errors and warnings: Provides documented error handling and troubleshooting guidance.