#GitHub Action Integration

Rsdoctor provides an official GitHub rsdoctor-action for easy integration of Rsdoctor analysis functionality in CI/CD workflows. Through GitHub Action, you can automatically perform bundle diff analysis on the build output and monitor and prevent bundle degradation, continuously optimizing project performance.

#Quick Start

#Step 1: Install Rsdoctor Plugin in Your Project

1. Follow the Quick Start guide to install the Rsdoctor plugin in your project and configure it according to your project type.

2. You need to use Brief mode and add 'json' to the type array so that the analysis data can be uploaded in the subsequent GitHub Action. For detailed configuration, see output options.

• Example below, Rsbuild integration example:

// rsbuild.config.ts
import { defineConfig } from '@rsbuild/core';
import { pluginReact } from '@rsbuild/plugin-react';
import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';

export default defineConfig({
  plugins: [pluginReact()],
  tools: {
    rspack: {
      plugins: [
        new RsdoctorRspackPlugin({
          output: {
            mode: 'brief',
            options: {
              type: ['json'],
            },
          },
        }),
      ],
    },
  },
});

#Step 2: Configure GitHub Workflow

Create a .github/workflows/ci.yml file in your GitHub repository as shown in the example below. Please note the following points:

• file_path: Required, path to the Rsdoctor JSON data file.
• target_branch: Optional, target branch name, defaults to 'main'. If you want to use a dynamic target branch, i.e., automatically get the target branch of the current pull request instead of a fixed main branch, you can use the following configuration:

target_branch: ${{ github.event_name == 'pull_request' && github.event.pull_request.base.ref || github.event.repository.default_branch }}

• dispatch_target_branch: Optional, used to specify the target branch when manually triggered (workflow_dispatch).

• on indicates when the workflow runs, commonly set to pull_request and push, and also supports workflow_dispatch for manual triggering.

  • On pull_request, Rsdoctor Action fetches baseline and current and performs bundle diff analysis.
  • On push (i.e., after PR merge), it updates and uploads the baseline.
  • workflow_dispatch allows you to manually trigger the workflow from the GitHub Actions page. This mode combines the behavior of push and pull_request: it uploads baseline data, and if dispatch_target_branch is specified, it also performs baseline comparison analysis.

• Before executing rsdoctor-action, build your project with the Rsdoctor plugin enabled to generate the Rsdoctor JSON data file.

name: Bundle Analysis

on:
  pull_request:
    types: [opened, synchronize, reopened]
  push:
    branches:
      - main # or your target branch name
  workflow_dispatch: # Optional, allows manual triggering
    inputs:
      target_branch:
        description: 'Target branch to compare against'
        required: false
        default: 'main'
        type: string

jobs:
  bundle-analysis:
    runs-on: ubuntu-latest

    permissions:
      # Allow commenting on commits
      contents: write
      # Allow commenting on issues
      issues: write
      # Allow commenting on pull requests
      pull-requests: write
      # Allow reading workflow runs and downloading artifacts for baseline comparison
      actions: read

    steps:
      - name: Checkout
        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4
        with:
          fetch-depth: 0
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Setup Pnpm
        run: |
          npm install -g corepack@latest --force
          corepack enable

      - name: Setup Node.js
        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version: 22
          cache: 'pnpm'

      - name: Install Dependencies and Build
        run: |
          pnpm install
          pnpm run build

      - name: Bundle Analysis
        uses: web-infra-dev/rsdoctor-action@main
        with:
          file_path: 'dist/.rsdoctor/rsdoctor-data.json'
          # Default 'main'. If you want to use a dynamic target branch, i.e., automatically get the target branch of the current pull request instead of a fixed main branch, you can use the following configuration:
          # ${{ github.event_name == 'pull_request' && github.event.pull_request.base.ref || github.event.repository.default_branch }}
          target_branch: 'main'
          # Target branch for manual trigger
          dispatch_target_branch: ${{ github.event.inputs.target_branch }}

#View Reports

After submitting the above configuration file to your repository, GitHub Actions will automatically run under the specified trigger conditions and generate Rsdoctor analysis reports. You will see bundle size change comparison prompts in GitHub CI, as shown below:

Additionally, clicking "Download Bundle Diff Report" allows you to download Rsdoctor's diff report for detailed diff data viewing.

For detailed Bundle Diff report content, see Bundle Diff Usage Guide.

#Troubleshooting

#Common Issues

Q: Action fails with "❌ Rsdoctor data file not found"

• Ensure your build process generates Rsdoctor JSON data, the default path is /rsdoctor-data.json.
• Check if file_path points to the correct location
• Verify that the Rsdoctor plugin is properly configured in your build tool

Q: If you see the message "No baseline data found", what does it mean?

• This is normal for the first run or for new repositories, because no baseline has been uploaded yet. The baseline data will be created after the first merge into the main branch.

#More Resources

• rsdoctor-action GitHub Repository