README.md

Datadog Build Plugins

A set of bundler plugins for:

• Webpack
• Vite
• esbuild
• Rollup
• Rspack

To interact with Datadog directly from your builds.

Note

If you want to upgrade from v1 to v2, please follow our migration guide.

Table of content

• Bundler Plugins
  • ESBuild
  • Rollup
  • Rspack
  • Vite
  • Webpack
• Features
  • RUM
  • Telemetry
• Configuration
  • auth.apiKey
  • logLevel
  • customPlugins
• Contributing
• License

Bundler Plugins

ESBuild

@datadog/esbuild-plugin

Installation

• Yarn

yarn add -D @datadog/esbuild-plugin

• NPM

npm install --save-dev @datadog/esbuild-plugin

Usage

const { datadogEsbuildPlugin } = require('@datadog/esbuild-plugin');

require('esbuild').build({
    plugins: [
        datadogEsbuildPlugin({
            // Configuration
        }),
    ],
});

Tip

It is important to have the plugin in the first position in order to report every other plugins.

📝 More details ➡️

Rollup

@datadog/rollup-plugin

Installation

• Yarn

yarn add -D @datadog/rollup-plugin

• NPM

npm install --save-dev @datadog/rollup-plugin

Usage

Inside your rollup.config.js.

import { datadogRollupPlugin } from '@datadog/rollup-plugin';

export default {
    plugins: [
        datadogRollupPlugin({
            // Configuration
        }),
    ],
};

Tip

It is important to have the plugin in the first position in order to report every other plugins.

📝 More details ➡️

Rspack

@datadog/rspack-plugin

Installation

• Yarn

yarn add -D @datadog/rspack-plugin

• NPM

npm install --save-dev @datadog/rspack-plugin

Usage

Inside your rspack.config.js.

const { datadogRspackPlugin } = require('@datadog/rspack-plugin');

module.exports = {
    plugins: [
        datadogRspackPlugin({
            // Configuration
        }),
    ],
};

Tip

It is important to have the plugin in the first position in order to report every other plugins.

📝 More details ➡️

Vite

@datadog/vite-plugin

Installation

• Yarn

yarn add -D @datadog/vite-plugin

• NPM

npm install --save-dev @datadog/vite-plugin

Usage

Inside your vite.config.js.

import { datadogVitePlugin } from '@datadog/vite-plugin';
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
        datadogVitePlugin({
            // Configuration
        }),
    ],
};

Tip

It is important to have the plugin in the first position in order to report every other plugins.

📝 More details ➡️

Webpack

@datadog/webpack-plugin

Installation

• Yarn

yarn add -D @datadog/webpack-plugin

• NPM

npm install --save-dev @datadog/webpack-plugin

Usage

Inside your webpack.config.js.

const { datadogWebpackPlugin } = require('@datadog/webpack-plugin');

module.exports = {
    plugins: [
        datadogWebpackPlugin({
            // Configuration
        }),
    ],
};

Tip

It is important to have the plugin in the first position in order to report every other plugins.

📝 More details ➡️

Features

RUM

Interact with our Real User Monitoring product (RUM) in Datadog directly from your build system.

datadogWebpackPlugin({
    rum?: {
        disabled?: boolean,
        sourcemaps?: {
            bailOnError?: boolean,
            dryRun?: boolean,
            intakeUrl?: string,
            maxConcurrency?: number,
            minifiedPathPrefix: string,
            releaseVersion: string,
            service: string,
        },
    }
});

📝 Full documentation ➡️

Telemetry

Display and send telemetry data as metrics to Datadog.

datadogWebpackPlugin({
    telemetry?: {
        disabled?: boolean,
        enableTracing?: boolean,
        endPoint?: string,
        output?: boolean
            | string
            | {
                destination: string,
                timings?: boolean,
                metrics?: boolean,
            },
        prefix?: string,
        tags?: string[],
        timestamp?: number,
        filters?: ((metric: Metric) => Metric | null)[],
    }
});

📝 Full documentation ➡️

Configuration

{
    auth?: {
        apiKey?: string;
    };
    customPlugins?: (options: Options, context: GlobalContext, log: Logger) => UnpluginPlugin[];
    logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'none';
    rum?: {
        disabled?: boolean;
        sourcemaps?: {
            bailOnError?: boolean;
            dryRun?: boolean;
            intakeUrl?: string;
            maxConcurrency?: number;
            minifiedPathPrefix: string;
            releaseVersion: string;
            service: string;
        };
    };
    telemetry?: {
        disabled?: boolean;
        enableTracing?: boolean;
        endPoint?: string;
        output?: boolean
            | string
            | {
                destination: string;
                timings?: boolean;
                metrics?: boolean;
            };
        prefix?: string;
        tags?: string[];
        timestamp?: number;
        filters?: ((metric: Metric) => Metric | null)[];
    };
}

auth.apiKey

default null

In order to interact with Datadog, you have to use your own API Key.

logLevel

default: 'warn'

Which level of log do you want to show.

customPlugins

default: []

This is a way for you to inject any Unplugin Plugin you want.

It's particularly useful to use our global, shared context of the main plugin.

Or to prototype some new plugins in the same environment.

{
    customPlugins: (options, context, log) => [{
        name: 'my-custom-plugin',
        buildStart() {
            log.info('Hello world');
        },
    }];
}

Your function will receive three arguments:

• options: The options you passed to the main plugin (including your custom plugins).
• context: The global context shared accross our plugin.
• log: A logger to display messages.

The context is a shared object that is mutated during the build process. It contains the following properties:

type GlobalContext = {
    // Mirror of the user's config.
    auth?: {
        apiKey?: string;
    };
    // More details on the currently running bundler.
    bundler: {
        name: string;
        fullName: string; // Including its variant.
        outDir: string; // Output directory
        // Added in `buildStart`.
        rawConfig?: any;
        variant: string; // Major version of the bundler (webpack 4, webpack 5), empty string otherwise.
    };
    // Added in `writeBundle`.
    build: {
        errors: string[];
        warnings: string[];
        // The list of entries used in the build.
        entries ? : {
            filepath: string;
            inputs: Input[],
            name: string;
            outputs: Output[]
            size: number;
            type: string,
        } [];
        // The list of inputs used in the build.
        inputs ? : {
            filepath: string;
            dependencies: Input[];
            dependents: Input[]
            name: string;
            size: number;
            type: string,
        } [];
        // The list of outputs generated by the build.
        outputs ? : {
            filepath: string;
            name: string;
            size: number;
            type: string,
            // Sourcemaps will use Outputs as their Inputs.
            inputs: (Input | Output)[]
        } [];
        start?: number;
        end?: number;
        duration?: number;
        writeDuration?: number;
    };
    cwd: string;
    // Added in `buildStart`.
    git?: {
        hash: string;
        remote: string;
        trackedFilesMatcher: [TrackedFilesMatcher](/packages/plugins/git/trackedFilesMatcher.ts);
    };
    inject: (item: { type: 'file' | 'code'; value: string; fallback?: @self }) => void;
    start: number;
    version: string;
}

Note

Some parts of the context are only available after certain hooks:

• context.bundler.rawConfig is added in the buildStart hook.
• context.build.* is populated in the writeBundle hook.
• context.git.* is populated in the buildStart hook.

Your function will need to return an array of Unplugin Plugins definitions.

Contributing

Check out CONTRIBUTING.md for more information about how to work with the build-plugins ecosystem.

License

MIT

Back to top ⬆️