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. You can also embed them 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 an app:

   npm create @datadog/apps@latest
   

2. Follow the interactive prompts to configure your app name and template.

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 (for example, http://localhost:5173/) to preview your app.

Backend functions

Files matching *.backend.ts or *.backend.js contain backend functions. Backend functions run server-side with access to your connections. 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, 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.

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;

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.

npm run upload

The following environment variables are available:

For production deployments, set up CI/CD with GitHub Actions. 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

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 upload your app on every push to the main branch, use the 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. 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.2
        with:
          datadog-api-key: ${{ secrets.DATADOG_API_KEY }}
          datadog-app-key: ${{ secrets.DATADOG_APP_KEY }}
          app-directory: .

Troubleshooting

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 enabled.

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

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, Volta, or fnm, or download from nodejs.org.

Further reading

お役に立つドキュメント、リンクや記事:

App BuilderDOCUMENTATION Embedded AppsDOCUMENTATION Access and AuthenticationDOCUMENTATION