---
title: "Apps hooks"
description: "Hand-written shim. Generated CRUD hooks via ./apps.gen
(`useListApps`, `useCreateApp`, `useRetrieveApp`, `useUpdateApp`,
`useDeleteApp`, `useRestoreApp`). Hooks below cover the build/deploy
mutations, the preview-session lifecycle, the live R2 file ops,
version-scoped REST file ops, env vars, and the custom domain — none
of which fit the manifest's standard CRUD kinds."
section: "Libraries"
group: "React hooks"
order: 406
---

## Usage

```tsx
import Aeontel from "@aeontel/sdk";
import { AeontelProvider, useListApps } from "@aeontel/react";

const client = new Aeontel(import.meta.env.VITE_AEONTEL_API_KEY);

function App() {
  return (
    <AeontelProvider client={client}>
      <AppsList workspaceId="wsp_abc123" />
    </AeontelProvider>
  );
}

function AppsList({ workspaceId }: { workspaceId: string }) {
  const { data, isLoading } = useListApps({ workspace_id: workspaceId });
  if (isLoading) return <p>Loading…</p>;
  return (
    <ul>
      {data?.data.map((a) => (
        <li key={a.id}>{a.name}</li>
      ))}
    </ul>
  );
}
```

## Hooks

### `useBuildApp` `composite`

Trigger a build for an app version. Returns the freshly-created Build
row (status `"pending"`) — poll via `useRetrieveBuild({ id: result.id })`.
Auto-invalidates build queries on success.

```ts
useBuildApp(options?: MutationOpts<Build, CreateBuildParams>)
```

**Types:** [Build](/types/build) · [CreateBuildParams](/types/create-build-params)

```ts
const build = useBuildApp();
build.mutate({ appVersionId: "appver_abc123" });
```

### `useCreateApp` `mutation`

Create a new app.

```ts
useCreateApp(options?: MutationOpts<App, CreateAppParams>)
```

**Types:** [App](/types/app) · [CreateAppParams](/types/create-app-params)

### `useCreateAppVersionFile` `mutation`

Create a file in a specific app version.

```ts
useCreateAppVersionFile(options?: MutationOpts<SuccessResponse, CreateAppVersionFileParams>)
```

**Types:** [SuccessResponse](/types/success-response) · [CreateAppVersionFileParams](/types/create-app-version-file-params)

### `useCreateDeploy` `mutation`

Create a deploy from a specific build, or deploy an app's latest
successful build. Use this when you have a `buildId` and want to ship
a specific build; for "deploy this app's default version", use
.

```ts
useCreateDeploy(options?: MutationOpts<Deploy, CreateDeployParams>)
```

**Types:** [Deploy](/types/deploy) · [CreateDeployParams](/types/create-deploy-params)

```ts
const deploy = useCreateDeploy();
deploy.mutate({ buildId: "bld_abc123" });
```

### `useDeleteApp` `mutation`

Soft-delete an app.

```ts
useDeleteApp(options?: MutationOpts<SuccessResponse, string>)
```

**Types:** [SuccessResponse](/types/success-response)

### `useDeleteAppEnvVar` `mutation`

Delete an env var from an app's Pages project.

```ts
useDeleteAppEnvVar(options?: MutationOpts<SuccessResponse, { appId: string; name: string; }>)
```

**Types:** [SuccessResponse](/types/success-response)

```ts
const del = useDeleteAppEnvVar();
del.mutate({ appId: "app_abc123", name: "API_URL" });
```

### `useDeleteAppVersionFile` `mutation`

Delete a file from a specific app version.

```ts
useDeleteAppVersionFile(options?: MutationOpts<SuccessResponse, DeleteAppVersionFileParams>)
```

**Types:** [SuccessResponse](/types/success-response) · [DeleteAppVersionFileParams](/types/delete-app-version-file-params)

### `useDeployApp` `composite`

Deploy a build. Returns the freshly-created Deploy row (status
`"pending"`) — poll via `useRetrieveDeploy({ id: result.id })`.
Auto-invalidates deploy queries on success.

```ts
useDeployApp(options?: MutationOpts<Deploy, DeployAppParams>)
```

**Types:** [Deploy](/types/deploy) · [DeployAppParams](/types/deploy-app-params)

```ts
const deploy = useDeployApp();
deploy.mutate({ id: "app_abc123", buildId: "bld_abc123" });
```

### `useGetAppDomainForApp` `query`

Get the custom domain attached to an app (or `null`). Takes the
**app** ID and reads `apps.getDomain` — different from the top-level
`useRetrieveAppDomain` which takes a domain row ID.

Pass `{ refetchInterval: POLL_ACTIVE }` to watch a `pending` row
flip to `active` while the customer's CNAME is being verified.

```ts
useGetAppDomainForApp(id: string, options?: QueryOpts<AppDomain | null>)
```

**Types:** [AppDomain](/types/app-domain)

```ts
const { data } = useGetAppDomainForApp("app_abc123");
```

### `useGetAppPreview` `query`

Poll the current state of a preview session. Pass `refetchInterval`
for polling.

```ts
useGetAppPreview(sessionId: string | null | undefined, options?: QueryOpts<AppPreviewSession>)
```

**Types:** [AppPreviewSession](/types/app-preview-session)

```ts
const { data } = useGetAppPreview(sessionId, { refetchInterval: 2000 });
```

### `useKeepalivePreview` `composite`

Heartbeat — keeps a preview session from being reaped.

```ts
useKeepalivePreview();
```

```ts
const keepalive = useKeepalivePreview();
keepalive.mutate({ sessionId: "appprv_abc" });
```

### `useListAppEnvVars` `query`

Fetch env vars for an app's Pages project.

```ts
useListAppEnvVars(appId: string, options?: QueryOpts<{ data: EnvVar[]; }>)
```

```ts
const { data } = useListAppEnvVars("app_abc123");
```

### `useListApps` `query`

List apps with pagination and optional filtering.

```ts
useListApps(params?: Omit<ListAppsParams, | > & { filter?: AppFilter; orderBy?: AppOrderBy[]; } & AppShorthands, options?: QueryOpts<Page<App>>)
```

**Types:** [ListAppsParams](/types/list-apps-params) · [AppFilter](/types/app-filter) · [AppOrderBy](/types/app-order-by) · [AppShorthands](/types/app-shorthands) · [Page](/types/page) · [App](/types/app)

### `useListAppVersionFiles` `query`

List files in a specific app version.

```ts
useListAppVersionFiles(appId: string, versionId: string, params?: { path?: string; }, options?: QueryOpts<AppFileListResponse>)
```

**Types:** [AppFileListResponse](/types/app-file-list-response)

```ts
const { data } = useListAppVersionFiles("app_abc123", "appver_def456", {
  path: "src",
});
```

### `usePurgeApp` `composite`

Permanently delete a soft-deleted app.

```ts
usePurgeApp(options?: MutationOpts<SuccessResponse, PurgeAppParams>)
```

**Types:** [SuccessResponse](/types/success-response) · [PurgeAppParams](/types/purge-app-params)

### `useReadAppVersionFile` `composite`

Read a file's content from a specific app version.

```ts
useReadAppVersionFile(versionId: string, path: string, options?: QueryOpts<AppFileContentResponse>)
```

**Types:** [AppFileContentResponse](/types/app-file-content-response)

```ts
const { data } = useReadAppVersionFile("appver_abc123", "src/index.ts");
```

### `useRemoveAppDomain` `mutation`

Detach the app's custom domain.

```ts
useRemoveAppDomain(options?: MutationOpts<SuccessResponse, RemoveAppDomainParams>)
```

**Types:** [SuccessResponse](/types/success-response) · [RemoveAppDomainParams](/types/remove-app-domain-params)

```ts
const remove = useRemoveAppDomain();
remove.mutate({ id: "app_abc123" });
```

### `useRestoreApp` `composite`

Restore a soft-deleted app.

```ts
useRestoreApp(options?: MutationOpts<App, string>)
```

**Types:** [App](/types/app)

### `useRetrieveApp` `query`

Get a single app by ID.

```ts
useRetrieveApp(id: string, options?: QueryOpts<App>)
```

**Types:** [App](/types/app)

### `useSetAppDomain` `composite`

Attach (or replace) the app's custom domain. Invalidates the
`appKeys.domain(id)` cache + the app detail so the overview shows
the new URL.

```ts
useSetAppDomain(options?: MutationOpts<AppDomain, SetAppDomainParams>)
```

**Types:** [AppDomain](/types/app-domain) · [SetAppDomainParams](/types/set-app-domain-params)

```ts
const set = useSetAppDomain();
set.mutate({ id: "app_abc123", hostname: "app.acme.com" });
```

### `useSetAppEnvVar` `composite`

Set (create or update) an env var on an app's Pages project.

```ts
useSetAppEnvVar(options?: MutationOpts<SuccessResponse, { appId: string; name: string; value: string; }>)
```

**Types:** [SuccessResponse](/types/success-response)

```ts
const setVar = useSetAppEnvVar();
setVar.mutate({ appId: "app_abc123", name: "API_URL", value: "https://..." });
```

### `useStartAppPreview` `composite`

Start (or wake) a live preview session for an app version.
Returns the session row in `hydrating` status — poll
`useGetAppPreview` until `status === "ready"` to get the URL.

```ts
useStartAppPreview(options?: MutationOpts<AppPreviewSession, { appVersionId: string; }>)
```

**Types:** [AppPreviewSession](/types/app-preview-session)

```ts
const start = useStartAppPreview();
start.mutate({ appVersionId: "appver_abc123" });
```

### `useStopAppPreview` `composite`

Stop a preview session.

```ts
useStopAppPreview(options?: MutationOpts<SuccessResponse, { sessionId: string; }>)
```

**Types:** [SuccessResponse](/types/success-response)

```ts
const stop = useStopAppPreview();
stop.mutate({ sessionId: "appprv_abc" });
```

### `useUpdateApp` `mutation`

Update an app (name, description, handle, publicAccess, defaultVersionId, config).

```ts
useUpdateApp(options?: MutationOpts<App, UpdateAppParams>)
```

**Types:** [App](/types/app) · [UpdateAppParams](/types/update-app-params)

### `useUpdateAppVersionFile` `mutation`

Update a file in a specific app version.

```ts
useUpdateAppVersionFile(options?: MutationOpts<SuccessResponse, UpdateAppVersionFileParams>)
```

**Types:** [SuccessResponse](/types/success-response) · [UpdateAppVersionFileParams](/types/update-app-version-file-params)