RelativeCI

In-depth bundle analysis and monitoring

Configure @relative-ci/agent webpack plugin

This page contains the setup guide for the current stable version of the agent(v4). Go to agent v5 beta to follow the setup guide for the new beta version.

Step 1. Install

npm install --save-dev @relative-ci/agent
yarn add --dev @relative-ci/agent
pnpm add -D @relative-ci/agent

Step 2. Configure

Webpack

Add RelativeCiAgentWebpackPlugin plugin to your webpack config:

webpack.config.js
const { RelativeCiAgentWebpackPlugin } = require('@relative-ci/agent');


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

Rspack

Add RelativeCiAgentWebpackPlugin plugin to your Rspack config:

rspack.config.js
const { RelativeCiAgentWebpackPlugin } = require('@relative-ci/agent');


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

Next.js

next.config.js
const { RelativeCiAgentWebpackPlugin } = require('@relative-ci/agent');


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


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


    return config;
  }
};

Gatsby

gatsby-node.js
const { RelativeCiAgentWebpackPlugin } = require('@relative-ci/agent');


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

Create React App

To setup @relative-ci/agent 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:

package.json
"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.

config-overrides.js
const { override, addWebpackPlugin } = require('customize-cra');
const { RelativeCiAgentWebpackPlugin } = require('@relative-ci/agent');


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


Need help to configure @relative-ci/agent webpack plugin for another framework?Contact us via email, Twitter, or GitHub!

Plugin options

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

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

  • payloadFilepath - save agent payload to disk for debugging

  • stats - Webpack stats options, default:

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

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:

RELATIVE_CI_KEY - required

Your project RelativeCI API key. To view the corresponding key for your project, navigate to https://app.relative-ci.com and go to the project Settings -> API Keys page.

RELATIVE_CI_ENDPOINT - required for RelativeCI Enterprise Cloud/Server

Set the RelativeCI ingestion URL corresponding to your setup.

More resources:

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

.github/workflow/build.yml
# ...
      - name: Project A - build
        run: cd project-a && npm build
        with:
          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 }}

Npm workspaces example

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

.github/workflow/build.yml
# ...
      - 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:

apps/app-1/package.json
{
  "name": "app-1",
  "scripts": {
    "build": "RELATIVE_CI_KEY=$APP_1_RELATIVE_CI_KEY npm run build"
  }
}

apps/app-2/package.json
{
  "name": "app-2",
  "scripts": {
    "build": "RELATIVE_CI_KEY=$APP_2_RELATIVE_CI_KEY npm run build"
  }
}

Lerna example

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

.github/workflow/build.yml
# ...
      - 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:

apps/app-1/package.json
{
  "name": "app-1",
  "scripts": {
    "build": "RELATIVE_CI_KEY=$APP_1_RELATIVE_CI_KEY npm run build"
  }
}

apps/app-2/package.json
{
  "name": "app-2",
  "scripts": {
    "build": "RELATIVE_CI_KEY=$APP_2_RELATIVE_CI_KEY npm run build"
  }
}


Setup done

View your RelativeCI projects

Configure your project:

GitHub Commit Status reviewGitHub Check ReportGitHub Pull Request CommentSlack NotificationInvite team members

Guides:

Webpack config for better monitoringnpm duplicate dependenciesAnalyze and compare bundle changes locally


Need help?Contact us via email, Twitter, or GitHub!

Identify and fix bundle regressions before shipping to production

Get started for freeGet in touch