Zodios

If you define an alias in your API definition, Zodios generates specialized hooks for those endpoints. This provides full auto-completion and automatic key management.

Query Aliases

Used for GET requests. Returns a QueryResult containing the response data, all standard react-query properties, the generated key, and an invalidate helper.

// Example: identical to hooks.useQuery("/users")
const { data: users, isLoading, isError, invalidate, key } = hooks.useGetUsers();

Immutable Query Aliases

Used for POST requests that act as queries. These are only available if you set immutable: true in your API definition.

// Example: identical to hooks.useImmutableQuery("/users/search")
const { data: users, isLoading, isError } = hooks.useSearchUsers({ name: "John" });

Mutation Aliases

Used for POST, PUT, PATCH, or DELETE endpoints.

// Example: identical to usePost("/users")
const { mutate } = hooks.useCreateUser();

Zodios provides a ZodiosHooks class that integrates your Zodios API client with @tanstack/solid-query. This allows you to use TanStack Query's powerful data fetching patterns (like infinite queries and mutations) while maintaining full type safety from your Zod schema definitions.

To use it:

1. Define your schemas using zod.
2. Define your API using makeApi.
3. Instantiate Zodios with your base URL and API definition.
4. Instantiate ZodiosHooks passing a key and your Zodios instance.
5. Wrap your application in a QueryClientProvider from @tanstack/solid-query.
6. Use the methods on the ZodiosHooks instance (e.g., createInfiniteQuery, createMutation, or alias-based methods like createCreateUser) within your Solid components.

import { QueryClient, QueryClientProvider } from "@tanstack/solid-query";
import { makeApi, Zodios } from "@zodios/core";
import { ZodiosHooks } from "../src";
import { z } from "zod";

// 1. Define Schemas
const userSchema = z.object({ id: z.number(), name: z.string() }).required();
const usersSchema = z.array(userSchema);

// 2. Define API
const api = makeApi([
  {
    method: "get",
    path: "/users",
    alias: "getUsers",
    response: usersSchema,
  },
  {
    method: "post",
    path: "/users",
    alias: "createUser",
    parameters: [{ name: "body", type: "Body", schema: z.object({ name: z.string() }).required() }],
    response: userSchema,
  },
]);

// 3. Setup Zodios and Hooks
const zodios = new Zodios("https://api.example.com", api);
const zodiosHooks = new ZodiosHooks("api-key", zodios);

// 4. Use in Component
const Users = () => {
  const users = zodiosHooks.createGetUsers({ params: { limit: 10 } });
  const userMutation = zodiosHooks.createCreateUser(undefined, {
    onSuccess: () => users.invalidate(),
  });

  return (
    <button onClick={() => userMutation.mutate({ name: "john" })}>Create</button>
  );
};

// 5. Provide QueryClient
const queryClient = new QueryClient();
export const App = () => (
  <QueryClientProvider client={queryClient}>
    <Users />
  </QueryClientProvider>
);

Zodios supports multipart/form-data using the requestFormat: "form-data" option.

Node.js Users: You must install the form-data package and polyfill globalThis.FormData before importing Zodios: globalThis.FormData = require("form-data");.

Alternatively, you can use your own multipart library (like form-data on Node) by defining the parameter schema as z.instanceof(FormData) and passing the headers manually.

// Option 1: Using integrated requestFormat
const apiClient = new Zodios(
  "https://mywebsite.com",
  [{ 
    method: "post",
    path: "/upload",
    alias: "upload",
    description: "Upload a file",
    requestFormat: "form-data",
    parameters:[
      {
        name: "body",
        type: "Body",
        schema: z.object({
          file: z.instanceof(File),
        }),
      }
    ],
    response: z.object({
      id: z.number(),
    }),
  }],
);
const id = await apiClient.upload({ file: document.querySelector('#file').files[0] });

// Option 2: Using custom FormData library (e.g. on Node)
import FormData from 'form-data';

const apiClient = new Zodios(
  "https://mywebsite.com",
  [{ 
    method: "post",
    path: "/upload",
    alias: "upload",
    description: "Upload a file",
    parameters:[
      {
        name: "body",
        type: "Body",
        schema: z.instanceof(FormData),
      }
    ],
    response: z.object({
      id: z.number(),
    }),
  }],
);
const form = new FormData();
form.append('file', document.querySelector('#file').files[0]);
const id = await apiClient.upload(form, { headers: form.getHeaders() });