Executable Examples

The repository contains two complete applications, each with separate RPC and HTTP views that demonstrate both factories. They share contracts and handlers: Vite uses a separate host, while Start serves its own routes. Both RPC endpoints accept request bodies up to 1 MiB and return HTTP 413 for larger bodies.

Example	Demonstrates	API host	Application URL
Vite React	RPC queries and streams beside buffered HTTP reads, writes, pagination, failures, and cancellation	Standalone server on port 3001, proxied by Vite	http://127.0.0.1:5173
TanStack Start	RPC and HTTP loaders, server rendering, hydration, navigation, mutations, and cancellation	Same-origin /rpc and /api/$ server routes	http://127.0.0.1:3000

Set up locally

Clone the repository, then run commands from its root:

git clone https://github.com/ueberBrot/effect-api-query.git
cd effect-api-query

Install the Node version in .node-version and the pnpm version in package.json, then install the workspace dependencies:

pnpm install --frozen-lockfile

The workspace includes Vite+. If vp is not on your shell’s PATH, prefix the commands below with pnpm exec, for example pnpm exec vp run vite-react-dev.

You can also use the included Dev Container: install Docker and the VS Code Dev Containers extension, open the clone, and choose Dev Containers: Reopen in Container. The container installs the declared tool versions and workspace dependencies, and forwards the application ports.

Run Vite React

vp run vite-react-dev

This task starts the standalone server and the Vite development server. Vite proxies /rpc and /api to the standalone host. The HTTP and RPC handlers share one user directory. To use another HTTP host, set VITE_HTTP_BASE_URL to its origin, such as http://127.0.0.1:3001; the contract already supplies /api. The application provides the demo authorization header through its HTTP client middleware.

Compare HTTP and RPC

The HTTP panel uses createHttpApiQueryUtils from effect-api-query; the existing RPC panels use createRpcQueryUtils from the same package root. The application owns both ready clients, their runners, and the QueryClient. During disposal, it cancels queries before releasing client resources.

Use the HTTP directory to read users, load another page, and create or delete a user. Each write explicitly invalidates both generated user prefixes, so the RPC directory reflects HTTP writes and the HTTP directory reflects RPC writes. The two adapters retain separate cache keys. Choose Reset directory to restore the deterministic shared data.

The HTTP user selector passes skipToken until a user is selected. HTTP request inputs use structured decoded parts such as params, query, and payload; RPC inputs retain their payload-constructor defaults. Deleting a user demonstrates an HTTP no-content mutation whose result remains undefined.

Trigger the HTTP failure to inspect EffectHttpApiQueryError and its preserved Cause. The package adds declaration identifiers to error metadata; upstream Causes can still contain request, response, or schema issue values.

Choose Start slow HTTP query, wait for HTTP: Ready to cancel, then choose Cancel HTTP query. After the HTTP request aborts, the example observes server interruption for that operation. Each panel owns a distinct operation ID, so cancelling an RPC query leaves a concurrent HTTP query running. This cancels observation and work in this handler; it does not compensate completed mutations. The RPC cancellable-command panel demonstrates explicit domain cancellation.

The executable sources are application ownership, HTTP contracts, and server handlers. The repository type-checks the application against the public package root and exercises it through the real server and browser suites.

Run TanStack Start

vp run tanstack-start-dev

This task starts one full-stack process. The browser and server-rendering clients call the Start-owned /rpc and /api/$ routes. Choose HTTP users to inspect the server-rendered directory and first page, reuse the hydrated cache, and try the same HTTP operations as in Vite React. Choose HTTP SSR failure to see the browser retry a failed server query that was omitted from dehydration.

Server rendering uses the trusted origin http://127.0.0.1:3000. If the Start server listens elsewhere, set the server-only EXAMPLE_API_ORIGIN environment variable to its HTTP(S) origin, without a path, credentials, query, or fragment. Browser requests stay on the same origin. See TanStack Start for request ownership, authentication, cache isolation, and hydration setup.

Pause a query until a user is selected

In either application, find Choose before fetching. With No user selected, the generated query uses { input: skipToken } and sends no lookup request. Select User 2: Edsger Dijkstra to load the user summary, then clear and reselect it within 30 seconds to reuse the cached result.

The skipped and active queries preserve the same select and staleTime options. The example uses ordinary useQuery; the TanStack Start loader leaves this interactive query paused during server rendering.

Compare full and bounded stream history

In either application, let the diagnostic stream finish, then choose Replay newest 2. The accumulated history retains only “Workspace synchronized” and “Ready”; earlier updates disappear as new ones arrive. Choose Replay full history to retain all four states again. The live query continues to show only “Ready”.

The bounded replay supplies maxChunks: 2 to streamedOptions. Both controls reuse the generated streamed key: the bound changes retention policy, not RPC identity. The application keeps the selected policy for subsequent refetches. TanStack Start also demonstrates this after hydrating its server snapshot.

Inspect request-local metadata

In either application’s diagnostics panel, choose Trigger declared failure. Its generated mutation options supply the x-request-source: diagnostics-panel RPC header. Application-wide authorization still comes from the shared client runner. The same rpcOptions input works with queries, infinite queries, and both stream builders; see Generated Builders.

Build the examples

Build either application without starting it:

vp run vite-react-build
vp run tanstack-start-build

Run in a local environment

Run either example locally or in the Dev Container. StackBlitz WebContainers cannot run these examples because Vite+ requires a native binding that is unavailable there.