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

# Quickstart

> From an empty folder to a live full-stack app — sign in, scaffold, build, deploy.

Four commands are the whole loop. Here they are one at a time.

<Steps>
  <Step title="Sign in">
    OAuth in your browser — no API keys to copy around. The CLI refreshes tokens for you, and
    the target instance comes from your token rather than a flag.

    ```bash theme={null}
    npx @xanots/sdk login
    ```

    <Note>
      On a remote shell, container, or Codespace — anywhere your browser can't reach this
      machine's `127.0.0.1` — add `--paste`. It prints the URL for you to open anywhere, and
      you paste the redirect back. See [Signing in & deploying](/guides/deploying).
    </Note>
  </Step>

  <Step title="Scaffold">
    `init` writes a complete project: a Vite frontend under `frontend/` (React 19 + shadcn/ui
    by default, or SvelteKit with `--framework svelte`), a XanoTS backend under `xano/`, and
    the `xano:export` / `xano:deploy` scripts already wired.

    ```bash theme={null}
    npx @xanots/sdk init my-app && cd my-app
    npm run dev                       # the frontend runs immediately
    ```

    In a terminal it asks two questions — framework and AI instruction files — each with a
    default. The theme is a flag, not a question:

    ```bash theme={null}
    npx @xanots/sdk init my-app --theme zinc-blue --dark toggle
    npx @xanots/sdk init my-app --web    # pick framework, palette, and add-ons in a browser
    ```

    The starter backend is empty but already compiles and deploys — grow it from the
    walkthrough in `xano/EXAMPLE.md`. For the flags, presets, theming, and add-ons, see
    [The scaffolded project](/guides/scaffold).
  </Step>

  <Step title="Build the frontend">
    ```bash theme={null}
    npm run build                     # → frontend/dist
    ```
  </Step>

  <Step title="Deploy both">
    One authenticated call ships your database schema, your APIs, your functions and
    triggers, **and** your compiled web app.

    ```bash theme={null}
    npx xanots deploy ./xano/index.ts --static ./frontend/dist
    ```

    ```
    → Deploying ./xano/index.ts → new ephemeral "my-app"
    ✓ Ephemeral e4f2-9ab1 deployed
    ! New ephemeral URL:
        https://e4f2-9ab1.xano.io                                         ← backend, live
        Expires in 1h 0m
    ✓ Config injected into 1 document: window.XANO_HOST                   ← backend URL, wired in
    ✓ Static host deployed
        https://my-app.xano.io                                            ← frontend, live
    ✓ Frontend is live                                                    ← edge confirmed serving THIS build
    ```
  </Step>
</Steps>

## The dev loop

Change your code and run step 4 again; the environment refreshes in seconds. The deploy
bakes the backend URL into your build as `window.XANO_HOST`, so the frontend never needs to
know it ahead of time — read it with a build-time fallback:

```ts theme={null}
const HOST = (typeof window !== "undefined" && window.XANO_HOST) || import.meta.env.VITE_XANO_HOST;
```

<Warning>
  Deploying again keeps the **backend** URL; the **frontend** one changes, because a deploy is
  a full replace and clears the environment's static hosting along with its workspace. Hand out
  the URL from the latest run.
</Warning>

[Signing in & deploying](/guides/deploying) covers the injection rules, serving stored files,
and headless CI runs.

## Wiring it by hand

Skip `init` — `npm install @xanots/sdk`, write your workspace in `xano/index.ts`, and steps 1
and 4 are unchanged. The entry must be an ES module (XanoTS defs are ESM-only), and a
TypeScript entry wants [`tsx`](https://tsx.is) installed (`npm i -D tsx`) — the CLI picks it
up automatically.

<Note>
  Node's own type stripping is not enough on its own: it loads a `.ts` file but does not remap
  the `./x.js` specifiers a workspace uses to import its own modules, so anything past a single
  file fails to resolve.
</Note>

## Testing what you deployed

The tests you author — a `tests` entry on a query, function, or middleware, or a standalone
`workflowTest()` — run against a deployed environment:

```bash theme={null}
npx xanots test run-all                       # the ephemeral you last deployed to
npx xanots test run-all --env ephemeral:pr-3  # or a named one
npx xanots test run-all --env workspace       # or your real workspace (this only reads)
```

A failing suite exits **5**, distinct from a crash, so CI can tell the two apart. To deploy
and prove it in one step, `xanots deploy ./xano/index.ts --test` — a failing test exits 5
**without** retracting the deploy, so the environment is live either way.