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 as App Builder apps and can also be embedded in other Datadog products such as dashboards and the Internal Developer Portal.

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 using your own backend code.
• Complex UI and logic: Full React and TypeScript control over components, state, and rendering.

Prerequisites

• Node.js version 20.12.0 or later. Check your version:

  node --version
  

• A Datadog API key and an application key with Actions API Access enabled. For instructions on creating keys, see API and Application Keys.

  To enable Actions API Access on an application key:

  1. Navigate to Organization Settings > Application Keys.
  2. Select your application key.
  3. Enable Actions API Access.

Scaffold an app

1. Run the scaffolding command to create a new app:

   npm create @datadog/apps
   

2. Follow the interactive prompts to configure your app name and template.
3. (Optional) Set up Datadog RUM for the app. This automatically sets up the Browser SDK for:
   • Real User Monitoring (RUM)
   • Error Tracking
   • Build metrics

Generated app structure

The scaffolded project includes:

Develop your app locally

1. Set your Datadog credentials as environment variables:

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

2. Start the development server:

   npm run dev
   

3. Open the URL shown in the terminal (http://localhost:5173/) to preview your app.

Backend functions

Files matching *.backend.ts or *.js contain backend functions. Backend functions run server-side with access to your API keys and are never shipped to the browser. The frontend imports and calls them like standard ES modules.

Backend functions can call any action in Datadog’s Action Catalog through the @datadog/action-catalog library. The Action Catalog provides reusable, pre-built actions for interacting with cloud providers, SaaS tools, and the Datadog API, so you can build functionality 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.

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;
}

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;

Upload your app

Run a production build to upload your app to Datadog:

npm run build

The following environment variables are available with npm run build:

By default, npm run build runs in dry run mode, which builds the app without uploading it to Datadog. Dry run mode is the recommended default for local development, where you typically don’t want to upload every local build.

For production deployments, set up CI/CD with GitHub Actions. DataDog/apps-github-action handles the upload step for you, so you don’t need to change dryRun for this workflow.

To upload from your local environment as an end-to-end test (for example, to verify that the build pipeline works before a release), set DD_APPS_UPLOAD_ASSETS:

DD_APPS_UPLOAD_ASSETS=1 npm run build

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

Publish and manage your apps

After you upload an app, it appears in your App Builder app list. From App Builder, you can:

• Publish your app
• Edit the app name and description
• Manage permissions
• Embed the app in dashboards, notebooks, and the Internal Developer Portal

Set up CI/CD with GitHub Actions

To automatically deploy your app on every push to the main branch, use the DataDog/apps-github-action GitHub Action. This action builds your app and deploys it to Datadog.

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

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

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

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.1
        with:
          datadog-api-key: ${{ secrets.DATADOG_API_KEY }}
          datadog-app-key: ${{ secrets.DATADOG_APP_KEY }}
          app-directory: .

Troubleshooting

Authentication errors

For authentication errors (such as 401 or Missing authentication token), or backend function call failures, verify that DD_API_KEY and DD_APP_KEY are set and that the application key has Actions API Access enabled.

Build succeeds but nothing uploads

The build defaults to dry run mode. Set DD_APPS_UPLOAD_ASSETS=1 or configure dryRun: false in vite.config.ts.

Node.js version errors during scaffolding

The scaffolding tool requires Node.js v20.12.0 or later. If you still encounter version errors on a supported version, try upgrading to v22. Use a version manager such as nvm, Volta, or fnm, or download from nodejs.org.

Further reading

Additional helpful documentation, links, and articles:

App BuilderDOCUMENTATION Embedded AppsDOCUMENTATION Access and AuthenticationDOCUMENTATION