Skip to main content
HttpClient is an Effect service that wraps Convex’s ConvexHttpClient. It provides query, mutation, and action methods that accept refs and automatically encode args and decode return values through the schemas defined in your function specs. Works in any JavaScript runtime that supports fetch.

​
Setup

Create the HttpClient layer by passing your Convex deployment URL. 
import { HttpClient } from "@confect/js";
import { Effect } from "effect";

const HttpClientLive = HttpClient.layer(
  "https://example-123.convex.cloud",
);
The layer can then be provided to any Effect that uses the HttpClient service.

​
Calling functions

Use the HttpClient service inside Effect.gen to call your functions with refs, the same way you would with @confect/react hooks or @confect/test. 
import { HttpClient } from "@confect/js";
import { Effect } from "effect";

import refs from "./confect/_generated/refs";

const program = Effect.gen(function* () {
  const client = yield* HttpClient.HttpClient;

  const notes = yield* client.query(refs.public.notes.list);

  const noteId = yield* client.mutation(refs.public.notes.insert, {
    text: "Hello from the server",
  });

  const result = yield* client.action(refs.public.random.getNumber);
});
Each method returns an Effect that can fail with HttpClientError (wrapping transport-level errors) or ParseResult.ParseError (if schema encoding or decoding fails).

​
Authentication

Set or clear the auth token before making authenticated requests. 
Effect.gen(function* () {
  const client = yield* HttpClient.HttpClient;

  yield* client.setAuth(token);

  const identity = yield* client.query(refs.public.auth.getIdentity);

  yield* client.clearAuth;
});

​
Running programs

Provide the HttpClient layer when running your program. 
import { HttpClient } from "@confect/js";
import { Console, Effect } from "effect";

const HttpClientLive = HttpClient.layer(
  "https://example-123.convex.cloud",
);

const program = Effect.gen(function* () {
  const client = yield* HttpClient.HttpClient;

  const notes = yield* client.query(refs.public.notes.list);
  yield* Console.log(notes);
});

Effect.runPromise(program.pipe(Effect.provide(HttpClientLive)));

​
Differences from ConvexHttpClient

ConvexHttpClientHttpClient
Functions referenced via api.module.fnFunctions referenced via refs
Args passed directly to Convex as-isArgs are schema-encoded from Type to Encoded before sending
Return values received directly as-isReturn values are schema-decoded from Encoded to Type
Methods return PromiseMethods return Effect with typed errors