• Clone the repo
• Install dependencies
• Architecture
  • @datadog/*: The packages we're publishing publicly on npm.
  • @dd/*: The packages we're only using internally.
• Create a new plugin
• Tests
• Integrity
• Formatting, Linting and Compiling
• Open Source compliance
• Documentation
• Publish a new public version
  • Recommended: Using GitHub Release (Automatic)
  • Alternative: Using Workflow Dispatch (Manual)
• Publish a new dev version
  • Using GitHub Actions Workflow
• Work with Datadog's Frontend monorepo
  • Requirements
  • Develop on both our monorepo and build-plugins locally
  • Update our frontend monorepo's version of plugins
  • Publish a dev/alpha/beta version of the plugins to consume in Datadog's Frontend monorepo
• Misc. Tooling

git clone [email protected]:DataDog/build-plugins.git

brew install volta
volta setup
# From the repo's root.
volta install node yarn

brew install yarn

Ensure dependencies are up to date in the repository.

# From the repo's root.
yarn

We have two types of workspaces:

Here's a diagram to help you understand the structure:

---
title: Datadog Build Plugins Design
---
stateDiagram-v2
    published: Published Packages
    productPlugins: Product Plugins
    errorTrackingPlugin: @dd/error-tracking-plugin
    rumPlugin: @dd/rum-plugin
    metricsPlugin: @dd/metrics-plugin
    esbuildplugin: @datadog/esbuild-plugin
    viteplugin: @datadog/vite-plugin
    rspackplugin: @datadog/rspack-plugin
    rollupplugin: @datadog/rollup-plugin
    webpackplugin: @datadog/webpack-plugin
    tools: @dd/tools
    factory: @dd/factory
    core: @dd/core
    types: Shared Types
    sharedHelpers: Shared Helpers
    sharedConstants: Shared Constants
    ahelpers: Aggregated Helpers
    atypes: Aggregated Types
    aplugins: Aggregated List of Plugins
    globalContext: Creation of the Global Context
    cli: Internal CLIs
    helpers: Tooling helpers
    internalPlugins: Internal Plugins
    analyticsPlugin: @dd/internal-analytics-plugin
    buildReportPlugin: @dd/internal-build-report-plugin
    bundlerReportPlugin: @dd/internal-bundler-report-plugin
    customHooksPlugin: @dd/internal-custom-hooks-plugin
    gitPlugin: @dd/internal-git-plugin
    injectionPlugin: @dd/internal-injection-plugin

    state internalPlugins {
        analyticsPlugin
        buildReportPlugin
        bundlerReportPlugin
        customHooksPlugin
        gitPlugin
        injectionPlugin
    }

    state core {
        sharedHelpers
        sharedConstants
        types
    }

    state published {
        esbuildplugin
        viteplugin
        rspackplugin
        rollupplugin
        webpackplugin
    }

    state productPlugins {
        errorTrackingPlugin
        rumPlugin
        metricsPlugin
    }

    state factory {
        ahelpers
        atypes
        aplugins
        globalContext
    }

    state tools {
        cli
        helpers
    }

    internalPlugins --> factory
    productPlugins --> factory: CONFIG_KEY<br/>helpers<br/>types<br/>getPlugins()
    core --> tools
    core --> factory
    core --> internalPlugins
    core --> productPlugins
    factory --> internalPlugins: Global Context
    factory --> productPlugins: Global Context
    factory --> published: Unplugin Factory
    published --> npm: types<br/>helpers<br/>datadogBundlerPlugin

We have a small wizard that will help you create a new plugin. Bootstrapping all the files you'll need to start coding.

yarn cli create-plugin

Then learn more about what you can use from the ecosystem.

We have a command to check the integrity of the files in the repository. To ensure everything is in order and follow our different compliance rules. This is also checked in the CI.

You can run this command and commit the changes if needed.

yarn cli integrity

It will:

• update all the .md files.
  • generate and update the Table of Contents delimited by <!-- #toc -->.
  • update the root README with the list of plugins and their configuration.
  • update the Custom Hooks' README with the list of hooks from the other plugins.
  • verify that all internal links are valid.
• update the necessary .ts and package.json files.
  • with the aggregated types from the plugins.
  • with the aggregated helpers from the plugins.
  • with the aggregated configurations from the plugins.
  • with the correct dependencies for our published packages.
• verify every plugins.
  • have a README.
  • have Codeowners.
• comply with our OSS rules (this can also be run with yarn oss).
  • add a header to each file.
  • update the LICENSES-3rdparty.csv, LICENSE, NOTICE and README.md with the correct licenses.
• update the lock files.
• auto format the codebase.
• typecheck the codebase.

We're using eslint and prettier to lint and format the code.

It's automatically done at save time when you're using VSCode or you can run a command to do it manually:

# With autofix
yarn format

# Without autofix
yarn lint

We're also using TypeScript.

# Typecheck everything
yarn typecheck:all

# Typecheck a specific workspace
yarn workspace <workspace> typecheck

# Build everything
yarn build:all

# Build a specific workspace
yarn workspace <workspace> build

# Watch changes on everything
yarn watch:all

# Watch a specific workspace
yarn workspace <workspace> watch

We follow a few rules, so we made a simple command to keep it compliant.

# Make the code compliant with our Open Source rules.
yarn oss

It will:

• update headers of each files.
• update LICENSES-3rdparty.csv, LICENSE, NOTICE and README.md with the correct licenses.

It is also run part of the yarn cli integrity CLI.

We try to keep the documentation as up to date as possible.

1. Run this action with the type of bump you need (patch, minor, major) and keep the master branch as target.

2. Review/accept the PR it created and merge it.

3. Create a new release

   a. Select the tag created in the bump PR.

b. Name it v{version} with the version created in the bump PR.

c. Generate the release notes, and clean it if needed.

4. Publish release.

Another action will takeover and publish the package on NPM.

Usually, after 4-5min, your version will be available from NPM.

You can also manually trigger the publish workflow from the master branch:

1. Ensure you're on the master branch
2. Update the version in package.json if needed (via the bump workflow or manually)
3. Go to the publish workflow
4. Click "Run workflow"
5. Select the master branch
6. Set channel to latest
7. Leave version empty (it will use the version from package.json)
8. Run the workflow

You can publish a version in the dev channel so you can easily test your changes in a different repository's CI.

The easiest way to publish a dev version is using the GitHub Actions workflow:

1. Go to the publish workflow
2. Click "Run workflow"
3. Select your feature branch (or master if publishing from there)
4. Set channel to dev
5. Set version to your dev version (e.g., 3.0.9-dev.0)
   • The version must follow the format X.Y.Z-dev.N
   • For example: 3.0.9-dev.0, 3.0.9-dev.1, etc.
6. Run the workflow

Wait a few minutes, and you're good to go.

yarn dev

yarn link-build-plugins

yarn update-build-plugins <version>

yarn update-build-plugins 2.5.1-dev.0

We have a CLI to help with some tasks.