> ## Documentation Index
> Fetch the complete documentation index at: https://sdk.docs.xano.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How it works

> How the Xano SDK turns TypeScript def objects into a bundle that Xano imports, what runs at build time and at request time, and how the SDK fits with XanoScript, the Xano CLI and the Xano editor.

Xano is one platform to build, run and govern AI-built software. The Xano SDK is the official
TypeScript SDK for it: your coding agent writes the database, the APIs and AI agents in
TypeScript, you run them on the Xano Engine on your machine, and then you deploy them to Xano.
This page explains what happens between the TypeScript in your repo and a running backend.

## From TypeScript to a running backend

You author **def objects**: plain TypeScript values made by factories such as `table()`,
`query()` and `apiGroup()`. You register them on one `workspace()` and default-export it from
`xano/index.ts`.

```ts theme={null}
import { workspace, table, query, apiGroup, f, s, ref, c, expr, col } from "@xano/sdk";

const post = table({
  name: "post",
  schema: {
    title: f.text({ required: true }),
    published: f.bool({ default: false }),
  },
});

const blog = apiGroup({ name: "blog", canonical: "blog" });

const listPosts = query({
  verb: "GET",
  apiGroup: blog,
  name: "list_posts",
  stack: [
    s.db.query({ table: post, where: expr(col("published"), "=", c.bool(true)), as: "rows" }),
  ],
  response: ref("rows"),
});

export default workspace("blog")
  .registerApiGroups([blog])
  .registerTables([post])
  .registerQueries([listPosts]);
```

A deploy then does three things:

1. **Compile.** The SDK loads `xano/index.ts` and compiles every registered def into a
   **bundle**: one JSON document in the format Xano imports.
2. **Import.** The bundle is imported into a backend: the Xano Engine on your machine, an
   ephemeral in Xano's cloud, or (through a release) your workspace or a tenant. The Engine and
   an ephemeral are the same backend, one local and one in the cloud.
3. **Record identity.** `xano/xano.lock` pins the identity of every object, so renaming a
   table renames it in place instead of dropping it and creating a new one.

Because the bundle is the unit, the same commit produces the same backend wherever it lands.
[Where your code goes](/ship/where-code-goes) lists every target and what a write to each one
changes.

## Build time and request time

Your TypeScript runs once, at build time. The `s.*` statement factories return data that
describes a step. They do not run it. Xano runs the compiled steps, in order, on every
request: a statement's `as` names a variable, and `response` is the HTTP body.

So every value that changes per request is a tagged value, resolved by Xano when the request
arrives: `ref("rows")` is a stack variable, `inp("title")` an input, `c.bool(true)` a
constant. JavaScript operators such as `+` or `===` do not compute over them. Compare with
`expr()` and compute with the `fl.*` filters instead.

<Warning>
  `ref("a") + ref("b")` does not add two numbers at request time. Write
  `withFilters(ref("a"), fl.add(ref("b")))`.
</Warning>

Requests share no memory. State lives in tables.

## Where the SDK sits in Xano

Xano stores your backend the same way whatever wrote it, so the SDK works alongside the rest
of Xano rather than replacing any of it.

| Surface | What it is | How it relates to the SDK |
| - | - | - |
| **The Xano editor** | Xano's own interface, with **Canvas View** and the **Function Stack** | After a deploy, the editor shows what your TypeScript compiled to. On the Engine, the deploy prints an **Open the builder** link. |
| **XanoScript** | Xano's native language | What you deploy from TypeScript is stored as the same objects XanoScript describes. `xanosdk release export` downloads a release as XanoScript. |
| **The Xano CLI** | Xano's command line for XanoScript projects ([docs.xano.com](https://docs.xano.com)) | A separate tool. In an SDK project you use `xanosdk`. |
| **An existing workspace** | A backend already running on Xano | `npx @xano/sdk init my-app --from workspace` reads it back as SDK TypeScript ([Existing workspace](/start/existing-workspace)). |

Building is one flow: your agent writes TypeScript, you run it on the Engine, you deploy it
to Xano. The editor is where the whole team reads what got built.

## Governing what ships

Code reaches your workspace through a **release**, a stored record of a backend that came up
and answered. You deploy to an ephemeral with tests, cut a release from it, and promote the
release onto a new Xano branch of your workspace. Live changes only when you say so. The
[Govern](/govern/overview) section covers drift, schema changes, guardrails for coding agents,
rollback and CI.

## Next

* [Quickstart](/start/quickstart): run a backend on the Xano Engine, with no account.
* [Build](/build/overview): tables, APIs, tasks, agents and tests, as def objects.
* [Glossary](/help/glossary): every term on this page, defined once.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.