Overview

Install Athena.js, create a client, and use the SDK guide map to jump to the right runtime surface.

Athena.js is the application-facing SDK for Athena gateway/data operations and Athena Auth client bindings. The docs in this section are organized around the runtime seams you actually touch: client construction, reads, writes, RPC, typed models, generator output, and auth.

For product and app integrations, prefer the published @xylex-group/athena package instead of copying older internal helpers.

Install

npm install @xylex-group/athena
# or
pnpm add @xylex-group/athena
# or
yarn add @xylex-group/athena

Install React only if you use the React runtime from @xylex-group/athena/react:

npm install react  # React >=17

Create a client

createClient(...) is the fastest path:

import { createClient } from "@xylex-group/athena";

const athena = createClient(
  "https://athena-db.com",
  process.env.ATHENA_API_KEY,
);

Optional defaults for every request:

const athena = createClient(
  "https://athena-db.com",
  process.env.ATHENA_API_KEY,
  {
    client: "your_client",
    headers: {
      "X-User-Id": currentUser.id ?? "",
    },
  },
);

If you want a more explicit setup surface, use the fluent builder:

import { AthenaClient, Backend } from "@xylex-group/athena";

const athena = AthenaClient.builder()
  .url(process.env.ATHENA_URL!)
  .key(process.env.ATHENA_API_KEY!)
  .options({
    client: "studio-web",
    backend: Backend.Athena,
    headers: { "X-App-Region": "eu" },
    auth: { baseUrl: process.env.ATHENA_AUTH_URL! },
  })
  .experimental({ traceQueries: true })
  .build();

Guides

Topic	What you will find
Queries and results	`.select()` chains, eager `.findMany(...)`, `.single()` / `.maybeSingle()`, and result typing
Type surface manifest	Long-form hub for the table DSL, derived helper types, schema bundles, generator artifacts, and error or operation typing
findMany AST and server contract	How object-tree reads compile to gateway payloads and what the current Athena server contract actually accepts
Select column aliases	`customName:columnName`, array form, qualified references, and alias behavior across reads and writes
Filtering	`.eq`, `.ilike`, `.in`, `.or`, `.not`, array operators — maps to `conditions`
Pagination and limits	`.limit`, `.offset`, `.range`, page-based `.currentPage` / `.pageSize` / `.totalPages` — maps to gateway body fields
Sorting	`.order()` and `sort_by: { field, direction }` on fetch, update, and delete
Mutations	`.insert`, `.update`, `.upsert`, `.delete` and safety rules
RPC	`.rpc()` — `POST /gateway/rpc` vs `GET /rpc/{name}`
Method surface reference	Grouped index of the public package surface across root exports, auth, React, cookies, and utils
React hook	`useAthenaGateway` and gateway helpers
Errors and retries	Structured `AthenaResult.error`, compatibility `errorDetails`, and reliability helpers

Minimal read

const result = await athena.from("users").findMany({
  select: {
    id: true,
    name: true,
  },
  where: {
    active: true,
  },
  limit: 25,
});

if (result.error) throw new Error(result.error.message);

Local validation (SDK repo)

When contributing to the npm package itself:

pnpm typecheck
pnpm check:all