Step 1. Install

npm install --save-dev @relative-ci/webpack-plugin@v5.0.0-rc.1

yarn add --dev @relative-ci/webpack-plugin@v5.0.0-rc.1

pnpm add -D @relative-ci/webpack-plugin@v5.0.0-rc.1

Step 2. Configure

Webpack

Add RelativeCIAgentPlugin plugin to your webpack config:

import RelativeCIAgentPlugin from '@relative-ci/webpack-plugin';

export default {
  // ... your webpack config
  plugins: [
    // ... other plugins
    new RelativeCIAgentPlugin()
  ]
};

import RelativeCIAgentPlugin from '@relative-ci/webpack-plugin';

export default {
  // ... your webpack config
  plugins: [
    // ... other plugins
    new RelativeCIAgentPlugin()
  ]
};

const RelativeCIAgentPlugin = require('@relative-ci/webpack-plugin');

module.exports = {
  // ... your webpack config
  plugins: [
    // ... other plugins
    new RelativeCIAgentPlugin()
  ]
};

• ExampleWebpack plugin

Rspack

Add RelativeCIAgentPlugin plugin to your Rspack config:

import RelativeCIAgentPlugin from '@relative-ci/webpack-plugin';

export default {
  // ... your rspack config
  plugins: [
    // ... other plugins
    new RelativeCIAgentPlugin()
  ]
};

import RelativeCIAgentPlugin from '@relative-ci/webpack-plugin';

export default {
  // ... your rspack config
  plugins: [
    // ... other plugins
    new RelativeCIAgentPlugin()
  ]
};

const RelativeCIAgentPlugin = require('@relative-ci/webpack-plugin');

module.exports = {
  // ... your rspack config
  plugins: [
    // ... other plugins
    new RelativeCIAgentPlugin()
  ]
};

• ExampleRspack webpack plugin

Next.js

Add RelativeCIAgentPlugin plugin to your Next.js config:

import RelativeCIAgentPlugin from '@relative-ci/webpack-plugin';

const nextConfig = {
  // ... your next.js config
  webpack: function (config, options) {
    const { dev, isServer } = options;

    if (!dev && !isServer) {
      config.plugins.push(
        new RelativeCIAgentPlugin(),
      );
    }

    // ... your custom Next.js webpack config

    return config;
  }
};

export default nextConfig;

import RelativeCIAgentPlugin from '@relative-ci/webpack-plugin';

const nextConfig = {
  // ... your next.js config
  webpack: function (config, options) {
    const { dev, isServer } = options;

    if (!dev && !isServer) {
      config.plugins.push(
        new RelativeCIAgentPlugin(),
      );
    }

    // ... your custom Next.js webpack config

    return config;
  }
};

export default nextConfig;

const RelativeCIAgentPlugin = require('@relative-ci/webpack-plugin');

module.exports = {
  webpack: function (config, options) {
    const { dev, isServer } = options;

    if (!dev && !isServer) {
      config.plugins.push(
        new RelativeCIAgentPlugin(),
      );
    }

    return config;
  }
};

• ExampleMozart409/next-relative-ci

Gatsby

Add RelativeCIAgentPlugin plugin to your Gatsby config:

const RelativeCIAgentPlugin = require('@relative-ci/webpack-plugin');

exports.onCreateWebpackConfig = ({ stage, actions }) => {
  if (stage === 'build-javascript') {
    actions.setWebpackConfig({
      plugins: [
        new RelativeCIAgentPlugin()
      ]
    });
  }
};

• ExampleGatsby webpack plugin

Create React App

To setup @relative-ci/webpack-plugin webpack plugin with create-react-app, you need to customize the default webpack config. That can be done by using react-app-rewired which is one of create-react-app's custom config solutions. You will also need customize-cra.

npm install --dev customize-cra react-app-rewired

yarn add --dev customize-cra react-app-rewired

pnpm add -D customize-cra react-app-rewired

Change your default scripts in package.json to:

"scripts": {
  "start": "react-app-rewired start",
  "build": "react-app-rewired build",
  "test": "react-app-rewired test"
}

Create a file config-overrides.js at the same level as package.json.

const { override, addWebpackPlugin } = require('customize-cra');
const RelativeCIAgentPlugin = require('@relative-ci/webpack-plugin');

module.exports = override(
  addWebpackPlugin(new RelativeCIAgentPlugin()),
);

Plugin options

• enabled - send bundle stats and build information to RelativeCI (default to env-ci isCi)

• failOnError - fail build when encountering errors (default: false)

• includeCommitMessage ( default true) - get current commit message (CI env data or git log -1 --pretty=%B) and send it to RelativeCI as part of the build information

• payloadFilepath - save agent payload to disk for debugging

• stats - Webpack stats options, default:

  {
    stats: {
      assets: true,
      chunks: true,
      modules: true,
    }
  }

• HelpDebug @relative-ci/webpack-plugin

Step 3. Configure Continuous Integration(CI) service

The plugin sends the build information and the bundle stats to RelativeCI ingestion service when enabled option is true. When running on supported CI services the option is set by default to true.

If you run multiple build tasks as part of your CI flow, consider to enable the plugin only for one task or setup one RelativeCI project for each build task.

Add environment variables

Follow the CI service guide to add the corresponding secrets and environment variables:

• GitHub Action
• CircleCI
• Vercel
• Netlify
• Jenkins

More resources:

• Build information
• Not supported CI services or non-CI environments

Monorepo

If you are using a monorepo setup and need to send the build information and the stats for multiple projects, use different API keys for each project.

GitHub Action example

# ...
      - name: Project A - build
        run: cd project-a && npm build
        env:
          RELATIVE_CI_KEY: ${{ secrets.RELATIVE_CI_KEY_PROJECT_A }}

      - name: Project B - build
        run: cd project-b && npm build
        env:
          RELATIVE_CI_KEY: ${{ secrets.RELATIVE_CI_KEY_PROJECT_B }}

• ExampleMonorepo Webpack plugin agent

Npm workspaces example

Pass projects RelativeCI key environment variables to the npm workspaces build task:

# ...
      - run: npm run build --workspaces
        env:
          APP_1_RELATIVE_CI_KEY: ${{ secrets.APP_1_RELATIVE_CI_KEY }}
          APP_2_RELATIVE_CI_KEY: ${{ secrets.APP_2_RELATIVE_CI_KEY }}

Add project specific RelativeCI key environment variable to the project's build script:

{
  "name": "app-1",
  "scripts": {
    "build": "RELATIVE_CI_KEY=$APP_1_RELATIVE_CI_KEY npm run build"
  }
}

{
  "name": "app-2",
  "scripts": {
    "build": "RELATIVE_CI_KEY=$APP_2_RELATIVE_CI_KEY npm run build"
  }
}

• Examplewebpack plugin agent example for npm workspaces

Lerna example

Pass projects RelativeCI key environment variables to the lerna build task:

# ...
      - run: npx lerna run build
        env:
          APP_1_RELATIVE_CI_KEY: ${{ secrets.APP_1_RELATIVE_CI_KEY }}
          APP_2_RELATIVE_CI_KEY: ${{ secrets.APP_2_RELATIVE_CI_KEY }}

Add project specific RelativeCI key environment variable to the project's build script:

{
  "name": "app-1",
  "scripts": {
    "build": "RELATIVE_CI_KEY=$APP_1_RELATIVE_CI_KEY npm run build"
  }
}

{
  "name": "app-2",
  "scripts": {
    "build": "RELATIVE_CI_KEY=$APP_2_RELATIVE_CI_KEY npm run build"
  }
}

• Examplewebpack plugin agent example for lerna