@datadog/create-apps

Scaffolding CLI for creating new Datadog Apps.

Usage

npm init @datadog/apps
# or
yarn init @datadog/apps

Choose a standalone app or monorepo. The standalone path then keeps the existing prompts:

1. Enter your app name (human-readable, e.g. "My Awesome App")
2. Enter a directory name (slugified default from the app name, e.g. "my-awesome-app")
3. Enter your Datadog site (defaults to datadoghq.com; use your custom subdomain if you have one)
4. Select a template

Your new Datadog App will be created in the specified directory.

Templates

• vite-react — A basic React application bundled with Vite.

Options

You can pass a target directory as the first positional argument, plus any of the flags below:

npm init @datadog/apps my-app --template vite-react -y
npm init @datadog/apps my-app --name "My App" --site datadoghq.eu -y

<directory>

Target directory for the new app. If omitted, you'll be prompted.

--name <name>

App name (user-facing). Skips the app name prompt.

The name is written to datadog-app.config.json and applied when the app is first uploaded. After that, rename the app in App Builder: changing name in the config doesn't rename an existing app.

--site <site>

Datadog site (e.g. datadoghq.com, datadoghq.eu, acme.datadoghq.com). Skips the site prompt. Validated against known Datadog sites.

--template <name>

Skip the template prompt and use the named template (e.g. vite-react).

--yes, -y

Accept all defaults without prompting. Requires a directory to be provided as a positional argument. New monorepos also require --app-directory.

--overwrite

Overwrite an existing target directory without prompting. Required to replace an existing directory in non-interactive (--yes) mode.

--skip-post-scaffold

Skip automatic setup commands (dependency installation, git initialization, etc.) for standalone apps. Workspace setup and lockfile validation cannot be skipped.

--validate

Validate the bundled templates and exit. Intended for CI / development of this CLI.

Monorepos

Use the latest release to create an npm workspace and its first Datadog App:

npm create @datadog/apps@latest -- my-workspace --monorepo \
  --app-directory first-app --name "First App" --site datadoghq.com

The workspace keeps apps under apps/*, shared packages under packages/*, shared TypeScript and ESLint configuration at the root, and one root package-lock.json. The root package.json records only the workspace layout (datadogApps.container); every app's site, identifier, and name stay in its own datadog-app.config.json.

When the command detects an existing generated workspace, it adds the requested app to that workspace instead of creating a nested repository:

npm create @datadog/apps@latest -- another-app --name "Another App"

Each app declares its own site. Interactive app creation prompts for it when --site is omitted; non-interactive creation uses datadoghq.com unless --site is passed.

Create a shared package from inside the workspace with:

npm create @datadog/apps@latest -- --package shared-utils

--monorepo

Create a new npm workspace and scaffold its first app. Without --yes, the initial prompt also offers this mode.

--app-directory <directory>

Set the first app's directory when creating a monorepo. --name remains the app's user-facing name when the app is first uploaded.

--container <directory>

Change the generated workspace's apps container from the default apps directory. Nested containers use / separators on every platform.

--package <name>

Add a shared package under packages/<name> in a detected workspace.

--github-repo <owner/repository>

For a new monorepo, create a private GitHub repository with gh, set it as origin, and push the initial commit. Standalone creation remains unchanged and does not accept this option.

--set-secrets

Set or update DATADOG_API_KEY and DATADOG_APP_KEY on an existing workspace repository. The repository is read from --github-repo or the current origin remote.

New monorepos include .github/workflows/validate-datadog-apps.yml for unconditional pull-request checks and .github/workflows/deploy-datadog-apps.yml for path-filtered default-branch uploads. Both execute .github/scripts/validate-workspace.mjs for React dependency alignment. The deployment workflow detects affected apps, installs the workspace once from the root lockfile, and runs DataDog/apps-github-action for each selected app directory with the root-installed CLI, each app's own site, and the Git commit as its version name, without requiring an app-owned upload script. The repository variable DD_SITE overrides every app's site when set.

What Gets Created

The CLI will:

• Create a new directory for your app
• Generate all necessary files from the selected template, including:
  • datadog-app.config.json — app definition and configuration (datadogSite, id, name, tags)
  • vite.config.ts — imports datadog-app.config.json and maps the flat fields into the datadogVitePlugin(...) call, layering env-dependent values on top
  • package.json (using the slugified directory name), source files, docs, and agent instructions
• Integrate Datadog features like ErrorTracking, Metrics, and more... thanks to our build-plugins.
• Optionally run setup commands (install dependencies, initialize git)

Next Steps

After your app is created:

cd your-app-name
npm run dev      # local dev server, with Datadog credentials resolved by datadog-apps
npm run build    # local production build (no upload)
npm run upload   # build, upload, and publish the app live with OAuth by default

The generated app uses API/App-key authentication when both DD_API_KEY and DD_APP_KEY are set. Otherwise, local backend function execution and app uploads use Datadog OAuth by default. API/App keys are optional for build metrics and Error Tracking sourcemap uploads. Refer to your app's generated AGENTS.md for specific instructions.

License

MIT