Skip to main content
Version: Next

wasp/client

Runtime configuration and environment variables of your app's client.

Enumerations​

HttpMethod​

The HTTP methods that a Route can use. These are the methods of Wasp's Operations and APIs, except for the ALL method that you can declare an API with.

Use it to describe a Route, for example when mocking an API with the mockApi helper that mockServer returns.

Enumeration Members​

Delete​

Delete: "DELETE"

Get​

Get: "GET"

Head: "HEAD"

Patch​

Patch: "PATCH"

Post​

Post: "POST"

Put​

Put: "PUT"

Type Aliases​

ClientConfig​

ClientConfig = object

The type of the config object.

Properties​

apiUrl​

apiUrl: string

The URL of your server (the app's backend), without a trailing slash, from the REACT_APP_API_URL env var.


ClientErrorContext​

ClientErrorContext = { componentStack?: string; source: "render"; } | { event: "error" | "unhandledrejection"; source: "window"; } | { source: "oauthCallback"; } | { source: "authForm"; } | { source: "optimisticUpdate"; }

Where an unexpected client error surfaced.

  • "render": While rendering a page or the root component. componentStack lists the components that led to the error, when React provides it.
  • "window": In the browser's error and unhandledrejection events, e.g. an error thrown in an event handler or a rejected promise nobody caught. event is the name of the browser event.
  • "oauthCallback": While finishing an OAuth login.
  • "authForm": While submitting one of Wasp's Auth UI forms.
  • "optimisticUpdate": In the updateQuery function of an optimistic update.

ClientOnErrorFn​

ClientOnErrorFn = (error, context) => void | Promise<void>

The type of the function you pass to the client.onError field of the app spec. Wasp calls it with every unexpected error on the client, after logging the error to the browser console.

It receives the error and the ClientErrorContext it surfaced in.

  • An HttpError, or the error the api client throws, is unexpected only with a status of 500 or above. A lower status means the server sent the error on purpose.
  • A failed Query or Action that your code handles is not unexpected. A failed Action that nobody catches arrives as a "window" error.
  • Wasp calls the function once per error, even if the error surfaces in more than one place.
  • Render errors arrive even when your own error boundaries catch them.
  • Wasp doesn't call the function while prerendering pages.
  • If the function throws, Wasp logs that error and keeps running.

Parameters​

error​

unknown

context​

ClientErrorContext

Returns​

void | Promise<void>

Example​

import type { ClientOnErrorFn } from "wasp/client";

export const onClientError: ClientOnErrorFn = (error, context) => {
errorTracker.capture(error, { source: context.source });
};

See​

Handling unexpected errors


Route​

Route = object

An HTTP method and path that identify an endpoint of your server.

Example​

import { HttpMethod, type Route } from "wasp/client";

const route: Route = { method: HttpMethod.Get, path: "/foo/bar" };

Properties​

method​

method: HttpMethod

path​

path: string

Variables​

config​

const config: ClientConfig

The client's configuration object.

Example​

import { config } from "wasp/client";

console.log(config.apiUrl);

See​

Accessing the configuration


env​

const env: ClientEnv

The client's validated environment variables.

It contains the env vars that Wasp defines (like REACT_APP_API_URL) and the ones you validate with the client.envValidationSchema field of the app spec. It leaves out any other env var, even if its name starts with REACT_APP_.

Wasp merges your validation schema with its own and validates import.meta.env with it, both when Vite starts (in development and when building) and when the client code loads.

Client env vars are embedded into the client code at build time, so anyone can read them. Never store secrets in them. Their names must start with REACT_APP_.

You can also read import.meta.env.REACT_APP_SOME_VAR_NAME directly, but we don't recommend it: import.meta.env isn't validated, and missing env vars can cause runtime errors.

Example​

import { env } from "wasp/client";

// Wasp-defined
const apiUrl = env.REACT_APP_API_URL;

// User-defined
const analyticsId = env.REACT_APP_ANALYTICS_ID;

See​

Referenced Types​

ClientEnv​

ClientEnv = object

The type of env.

See​

Wasp client env vars

Indexable​

[name: string]: unknown

The env vars from your client.envValidationSchema, with the types your Zod schema outputs.

Properties​

REACT_APP_API_URL​

REACT_APP_API_URL: string

The URL of your server, which the client uses to call it. Wasp sets it during development (wasp start). Your deployed app requires it: set it to the URL of your server as the user's browser sees it (with the DNS and proxies considered).