RelativeCI

Automated bundle analysis, reviews and monitoring

Configure @relative-ci/agent webpack plugin

This page contains the setup guide for the previous version of the agent (v4). Go to agent v5 to follow the setup guide for the latest stable version.

Migrate from v4 to v5

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:

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


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

Rspack

Add RelativeCiAgentWebpackPlugin plugin to your Rspack config:

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


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

Next.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

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:

"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 { 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 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 enabling the plugin only for one task or setting up 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

# ...
- 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:

# ...
- 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"
  }
}

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"
  }
}


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!

Quickly identify and fix bundle regressions
before shipping to production

Get started for freeGet in touch