---
title: Apps
description: >-
  Build and deploy custom Apps locally using a code-based development workflow
  with React, backend functions, and a CLI.
breadcrumbs: Docs > Actions > Apps
---

# Apps

{% callout %}
# Important note for users on the following Datadog sites: app.ddog-gov.com, us2.ddog-gov.com

{% alert level="danger" %}
This product is not supported for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site.md). ().
{% /alert %}

{% /callout %}

## Overview{% #overview %}

With Apps, you build applications locally as code with React and TypeScript (or JavaScript), using your standard development workflow.

Apps use the same [permissions model](https://docs.datadoghq.com/actions/app_builder/access_and_auth.md) as [App Builder apps](https://docs.datadoghq.com/actions/app_builder.md). You can also embed them in other Datadog products, such as [dashboards and the Internal Developer Portal](https://docs.datadoghq.com/actions/app_builder/embedded_apps.md).

Choose Apps when you need:

- **Team collaboration**: Multiple engineers contributing to the same app, with code review and version history through your existing source control.
- **Source control and CI/CD**: Store your app in GitHub and deploy automatically on merge.
- **AI-assisted development**: Use your preferred local tooling (such as Cursor, GitHub Copilot, or Claude) to generate and refine code.
- **Custom cloud providers and APIs**: Integrate with services beyond the [Action Catalog](https://docs.datadoghq.com/actions/actions_catalog.md) using your own backend code.
- **Complex UI and logic**: Full React and TypeScript control over components, state, and rendering.

## Prerequisites{% #prerequisites %}

- **Node.js version 20.12.0 or later**. Check your version:

  ```shell
  node --version
  ```

- A Datadog **API key** and an **application key** with [Actions API Access](https://docs.datadoghq.com/account_management/api-app-keys.md#actions-api-access) enabled. For instructions on creating keys, see [API and Application Keys](https://docs.datadoghq.com/account_management/api-app-keys.md).

To enable Actions API Access on an application key:

  1. Navigate to [**Organization Settings > Application Keys**](https://app.datadoghq.com/organization-settings/application-keys).
  1. Select your application key.
  1. Enable **Actions API Access**.

## Scaffold an app{% #scaffold-an-app %}

1. Run the scaffolding command to create an app:
   ```shell
   npm create @datadog/apps@latest
   ```
1. Follow the interactive prompts to configure your app name and template.

### Generated app structure{% #generated-app-structure %}

The scaffolded project includes:

| File or directory     | Description                                                                                                                    |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `src/App.tsx`         | Root UI component (React)                                                                                                      |
| `src/**/*.backend.ts` | Backend functions that run server-side with access to [Datadog connections](https://docs.datadoghq.com/actions/connections.md) |
| `vite.config.ts`      | Build configuration with [`@datadog/vite-plugin`](https://github.com/DataDog/build-plugin) pre-configured                      |
| `package.json`        | Dependencies and scripts (`dev`, `build`, `upload`)                                                                            |

## Develop your app locally{% #develop-your-app-locally %}

1. Set your Datadog credentials as environment variables:

   ```shell
   export DD_API_KEY="<YOUR_API_KEY>"
   export DD_APP_KEY="<YOUR_APPLICATION_KEY>"
   ```

1. Start the development server:

   ```shell
   npm run dev
   ```

1. Open the URL shown in the terminal (for example, `http://localhost:5173/`) to preview your app.

### Backend functions{% #backend-functions %}

Files matching `*.backend.ts` or `*.backend.js` contain backend functions. Backend functions run server-side with access to your [connections](https://docs.datadoghq.com/actions/connections.md). The frontend imports and calls them like standard ES modules.

Backend functions can call any action in Datadog's [Action Catalog](https://docs.datadoghq.com/actions/actions_catalog.md) through the [`@datadog/action-catalog`](https://www.npmjs.com/package/@datadog/action-catalog) library. The Action Catalog provides reusable, prebuilt actions for interacting with cloud providers, SaaS tools, and the Datadog API. You can build on top of existing integrations instead of writing API clients from scratch.

The library is a fully typed TypeScript client that wraps integrations, including AWS, Azure, GCP, the Datadog API, GitHub, GitLab, Slack, Jira, PagerDuty, ServiceNow, OpenAI, Anthropic, and generic HTTP. Importing actions from `@datadog/action-catalog` gives you typed inputs and responses for each action.

{% collapsible-section %}
#### Example backend function

Create a backend function that lists hosts through the Action Catalog:

**src/listHosts.backend.ts**

```typescript
import { listHosts, type ListHostsResponse } from '@datadog/action-catalog/dd/hosts';

export async function getHosts(filter?: string): Promise<ListHostsResponse> {
    const response = await listHosts({
        inputs: {
            filter: filter ?? '*',
            count: 10,
            include_hosts_metadata: true,
        },
    });
    return response;
}
```

Then call it from your app's `App.tsx`:

**src/App.tsx**

```tsx
import { useState, useEffect } from 'react';
import { getHosts } from './listHosts.backend';

function App() {
    const [hostCount, setHostCount] = useState<number>(0);

    useEffect(() => {
        getHosts().then((response) => {
            setHostCount(response.host_list?.length ?? 0);
        });
    }, []);

    return (
        <div style={{ padding: '2rem', textAlign: 'center' }}>
            <h1>Welcome to my-app</h1>
            <p>Monitoring {hostCount} hosts</p>
        </div>
    );
}

export default App;
```

{% /collapsible-section %}

## Build and upload your app{% #build-and-upload-your-app %}

Use `npm run build` to build the app locally without uploading it. This is the recommended default for local development, where you typically don't want to upload every build.

Use `npm run upload` to build and upload the app to Datadog. This runs `vite build` with `DD_APPS_UPLOAD_ASSETS=1`.

```shell
npm run upload
```

The following environment variables are available:

| Variable                | Description                                                                                                                         |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `DD_API_KEY`            | Datadog API key.                                                                                                                    |
| `DD_APP_KEY`            | Datadog application key.                                                                                                            |
| `DD_APPS_VERSION_NAME`  | Optional. The version name for the uploaded app version. Must be a unique string per app. If unset, Datadog assigns a version name. |
| `DD_APPS_UPLOAD_ASSETS` | If set, uploads built assets to Datadog. Set automatically by `npm run upload`.                                                     |

For production deployments, set up CI/CD with GitHub Actions. [`DataDog/apps-github-action`](https://github.com/DataDog/apps-github-action) handles the upload step for you.

After a successful upload, the build output displays a URL where your app is accessible in Datadog.

## Publish and manage your apps{% #publish-and-manage-your-apps %}

After you upload an app, it appears in your [App Builder](https://app.datadoghq.com/app-builder/apps/list) app list. From App Builder, you can:

- [Publish your app](https://docs.datadoghq.com/actions/app_builder/build.md#customize-your-app)
- [Edit the app name and description](https://docs.datadoghq.com/actions/app_builder/build.md#customize-your-app)
- Manage [permissions](https://docs.datadoghq.com/actions/app_builder/access_and_auth.md#app-permissions)
- [Embed the app](https://docs.datadoghq.com/actions/app_builder/embedded_apps.md) in dashboards, notebooks, and the Internal Developer Portal

{% alert level="danger" %}
The following App Builder features are not available for locally-built apps:
- UI editing with drag-and-drop components
- Variables, events, and expressions managed in the App Builder UI
To change an app's UI or logic, update the code in your local project and re-upload.
{% /alert %}

## Set up CI/CD with GitHub Actions{% #set-up-cicd-with-github-actions %}

To automatically upload your app on every push to the `main` branch, use the [`DataDog/apps-github-action`](https://github.com/DataDog/apps-github-action) GitHub Action. This action builds your app and uploads it to Datadog.

If your organization is not on US1 (`datadoghq.com`), set `auth.site` in `vite.config.ts` to your [Datadog site](https://docs.datadoghq.com/getting_started/site.md). The build reads this configuration when uploading the app, so the same setting also applies to local development. Your Datadog site is ``.

{% callout %}
# Important note for users on the following Datadog sites: us3.datadoghq.com, us5.datadoghq.com, app.datadoghq.eu, ap1.datadoghq.com, ap2.datadoghq.com



```ts
datadogVitePlugin({
  auth: {
    site: '<YOUR_DATADOG_SITE>',
  },
});
```


{% /callout %}

Create `.github/workflows/cd.yml` in your app's repository:

```yaml
name: Continuous Deployment
on:
  push:
    branches:
      - main

permissions:
  contents: read

jobs:
  deploy-app:
    name: Deploy Datadog App
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write

    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Setup Node.js
        uses: actions/setup-node@v6

      - name: Deploy
        uses: DataDog/apps-github-action@v0.0.2
        with:
          datadog-api-key: ${{ secrets.DATADOG_API_KEY }}
          datadog-app-key: ${{ secrets.DATADOG_APP_KEY }}
          app-directory: .
```

## Troubleshooting{% #troubleshooting %}

### Authentication errors{% #authentication-errors %}

Authentication errors (such as 401 or `Missing authentication token`) and backend function call failures usually point to missing or invalid credentials. Verify that `DD_API_KEY` and `DD_APP_KEY` are set, and that the application key has [Actions API Access](https://docs.datadoghq.com/account_management/api-app-keys.md#actions-api-access) enabled.

### Build succeeds but nothing uploads{% #build-succeeds-but-nothing-uploads %}

Make sure you ran `npm run upload` (not `npm run build`), and that `dryRun` in `vite.config.ts` is not set to `true`.

### Node.js version errors during scaffolding{% #nodejs-version-errors-during-scaffolding %}

The scaffolding tool requires Node.js 20.12.0 or later. If you see errors even on a supported version, upgrade to v22. Use a version manager such as [nvm](https://github.com/nvm-sh/nvm), [Volta](https://volta.sh), or [fnm](https://github.com/Schniz/fnm), or download from [nodejs.org](https://nodejs.org).

## Further reading{% #further-reading %}

- [App Builder](https://docs.datadoghq.com/actions/app_builder.md)
- [Embedded Apps](https://docs.datadoghq.com/actions/app_builder/embedded_apps.md)
- [Access and Authentication](https://docs.datadoghq.com/actions/app_builder/access_and_auth.md)