SonarQube/SonarCloud Scanner for JavaScript Projects

Common errors

• Error: Node.js version is not supported.

  cause Running `sonarqube-scanner` (version 4.x or higher) with a Node.js version older than 18.
  fix Upgrade your Node.js environment to version 18 or newer (e.g., `nvm install 18 && nvm use 18`).

• Error: SonarQube server not found at URL: [YOUR_URL]

  cause The configured SonarQube server URL is incorrect, inaccessible, or the server is not running.
  fix Verify the `serverUrl` option in your scanner configuration. Ensure the SonarQube server is running and accessible from the machine initiating the scan. Check firewall rules or proxy settings.

• Error: You must install 'sonarqube-scanner' globally to run the 'sonar' command.

  cause Attempting to use the `sonar` command without installing the package globally.
  fix Install the package globally using `npm install -g sonarqube-scanner` or use `npx sonarqube-scanner` instead to run it without global installation.

Warnings

• breaking Node.js version requirements have increased. Versions 4.x and above require Node.js 18+, while v3.x required Node.js 16+. Older versions (v2.9.1 and below) supported Node.js 14+.
  Fix: Upgrade your Node.js runtime to version 18 or higher. If unable to upgrade, use a compatible older version of `sonarqube-scanner` (e.g., v3.x for Node 16+).
• breaking The package `sonarqube-scanner` is officially published under this name. However, the project's README and quickstart examples frequently refer to `@sonar/scan` for installation and `npx` commands. This creates confusion regarding the correct package identifier. Always use `sonarqube-scanner` when installing or importing programmatically unless official documentation explicitly clarifies a renaming.
  Fix: When installing via npm, use `npm install sonarqube-scanner`. When importing programmatically, use `import scanner from 'sonarqube-scanner';`. For `npx` or global CLI usage, follow the project's specific instructions, which currently point to `npx @sonar/scan` or the `sonar` command for global installations.
• gotcha Security vulnerabilities CVE-2024-21538 and CVE-2025-27152 (related to Axios) were fixed in version 4.3.0. Running older versions exposes projects to these known vulnerabilities.
  Fix: Upgrade `sonarqube-scanner` to version 4.3.0 or higher to mitigate these security risks. Regularly update dependencies to benefit from ongoing security patches.
• gotcha The `scanner` function's callback is executed upon the completion of the local scanning process, not necessarily after the SonarQube server has finished processing the analysis report. To get the actual quality gate status or detailed analysis results, you typically need to poll the SonarQube server API.
  Fix: Do not solely rely on the callback for pipeline success/failure. Implement additional steps to query the SonarQube/SonarCloud API for the project's quality gate status after the scan has been submitted.

Install

• npm install sonarqube-scanner npm
• yarn add sonarqube-scanner yarn
• pnpm add sonarqube-scanner pnpm

Imports

• default
  wrong:

  const scanner = require('sonarqube-scanner').default;

  correct:

  import scanner from 'sonarqube-scanner';
  // or
  import * as scanner from 'sonarqube-scanner';

  The package exports a default function (callable directly). While CommonJS `require` is shown in some docs, ESM imports are preferred for Node.js >=18.
• scanner function
  wrong:

  import { scanner } from 'sonarqube-scanner';

  correct:

  import scanner from 'sonarqube-scanner';
  scanner({ /* options */ }, callback);

  The primary API is a default-exported function, not a named export. Ensure to import the default.
• Command Line Interface (CLI)

  npx sonarqube-scanner
  # or globally installed
  sonar

  The package can be invoked via `npx` without explicit installation, or via the `sonar` command if installed globally. Note that the README refers to `@sonar/scan` for npx usage, but the actual package name is `sonarqube-scanner`.

Quickstart

This TypeScript example demonstrates how to programmatically trigger a SonarQube analysis for a project, configuring common properties like project key, sources, tests, and coverage reports. It uses environment variables for sensitive data.

import scanner from 'sonarqube-scanner';
import path from 'node:path';

const projectKey = process.env.SONAR_PROJECT_KEY ?? 'my-typescript-project';
const serverUrl = process.env.SONAR_SERVER_URL ?? 'http://localhost:9000';
const token = process.env.SONAR_TOKEN ?? ''; // Optional, for authenticated scans

console.log(`Starting SonarQube scan for project: ${projectKey}`);

scanner(
  {
    serverUrl: serverUrl,
    token: token, // Pass token only if required for authentication
    options: {
      'sonar.projectKey': projectKey,
      'sonar.projectName': projectKey, // Often same as key
      'sonar.projectVersion': '1.0.0',
      'sonar.sources': 'src',
      'sonar.tests': 'test',
      'sonar.typescript.lcov.reportPaths': 'coverage/lcov.info',
      'sonar.javascript.maxFileSize': '10000',
      'sonar.sourceEncoding': 'UTF-8',
      'sonar.exclusions': '**/node_modules/**, **/*.d.ts',
      'sonar.host.url': serverUrl, // Redundant if serverUrl is set directly, but common
      // Add other properties as needed, e.g., 'sonar.login': token for older versions
    },
  },
  () => {
    console.log('SonarQube scan finished or failed (check SonarQube logs).');
    // The callback is invoked regardless of success/failure, 
    // so check SonarQube server for actual status.
  }
);