{"id":12055,"library":"sonarqube-scanner","title":"SonarQube/SonarCloud Scanner for JavaScript Projects","description":"The `sonarqube-scanner` package provides a Node.js-based client to initiate code analysis on SonarQube Server and SonarCloud for JavaScript, TypeScript, and other compatible projects. Unlike the Java-based SonarScanner CLI, this module does not require a Java Runtime Environment, streamlining integration into JavaScript-centric build pipelines. The current stable version is 4.3.6, with frequent releases primarily focused on dependency updates, minor bug fixes, and security patches. It offers both a command-line interface (via `npx @sonar/scan` or global installation) and a programmatic API for integration into Node.js applications. Key differentiators include its lightweight nature for Node.js environments and direct support for `sonar.projectKey`, `sonar.sources`, and other SonarQube analysis properties.","status":"active","version":"4.3.6","language":"javascript","source_language":"en","source_url":"https://github.com/SonarSource/sonar-scanner-npm","tags":["javascript","sonarqube","sonarcloud","sonarqube-scanner","sonarqube-runner","sonar-scanner","sonar-runner","typescript"],"install":[{"cmd":"npm install sonarqube-scanner","lang":"bash","label":"npm"},{"cmd":"yarn add sonarqube-scanner","lang":"bash","label":"yarn"},{"cmd":"pnpm add sonarqube-scanner","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime environment requirement for the package. Version 18 or higher is required for v4+.","package":"node","optional":false}],"imports":[{"note":"The package exports a default function (callable directly). While CommonJS `require` is shown in some docs, ESM imports are preferred for Node.js >=18.","wrong":"const scanner = require('sonarqube-scanner').default;","symbol":"default","correct":"import scanner from 'sonarqube-scanner';\n// or\nimport * as scanner from 'sonarqube-scanner';"},{"note":"The primary API is a default-exported function, not a named export. Ensure to import the default.","wrong":"import { scanner } from 'sonarqube-scanner';","symbol":"scanner function","correct":"import scanner from 'sonarqube-scanner';\nscanner({ /* options */ }, callback);"},{"note":"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`.","symbol":"Command Line Interface (CLI)","correct":"npx sonarqube-scanner\n# or globally installed\nsonar"}],"quickstart":{"code":"import scanner from 'sonarqube-scanner';\nimport path from 'node:path';\n\nconst projectKey = process.env.SONAR_PROJECT_KEY ?? 'my-typescript-project';\nconst serverUrl = process.env.SONAR_SERVER_URL ?? 'http://localhost:9000';\nconst token = process.env.SONAR_TOKEN ?? ''; // Optional, for authenticated scans\n\nconsole.log(`Starting SonarQube scan for project: ${projectKey}`);\n\nscanner(\n  {\n    serverUrl: serverUrl,\n    token: token, // Pass token only if required for authentication\n    options: {\n      'sonar.projectKey': projectKey,\n      'sonar.projectName': projectKey, // Often same as key\n      'sonar.projectVersion': '1.0.0',\n      'sonar.sources': 'src',\n      'sonar.tests': 'test',\n      'sonar.typescript.lcov.reportPaths': 'coverage/lcov.info',\n      'sonar.javascript.maxFileSize': '10000',\n      'sonar.sourceEncoding': 'UTF-8',\n      'sonar.exclusions': '**/node_modules/**, **/*.d.ts',\n      'sonar.host.url': serverUrl, // Redundant if serverUrl is set directly, but common\n      // Add other properties as needed, e.g., 'sonar.login': token for older versions\n    },\n  },\n  () => {\n    console.log('SonarQube scan finished or failed (check SonarQube logs).');\n    // The callback is invoked regardless of success/failure, \n    // so check SonarQube server for actual status.\n  }\n);\n","lang":"typescript","description":"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."},"warnings":[{"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+).","message":"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+.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<4.3.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Upgrade your Node.js environment to version 18 or newer (e.g., `nvm install 18 && nvm use 18`).","cause":"Running `sonarqube-scanner` (version 4.x or higher) with a Node.js version older than 18.","error":"Error: Node.js version is not supported."},{"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.","cause":"The configured SonarQube server URL is incorrect, inaccessible, or the server is not running.","error":"Error: SonarQube server not found at URL: [YOUR_URL]"},{"fix":"Install the package globally using `npm install -g sonarqube-scanner` or use `npx sonarqube-scanner` instead to run it without global installation.","cause":"Attempting to use the `sonar` command without installing the package globally.","error":"Error: You must install 'sonarqube-scanner' globally to run the 'sonar' command."}],"ecosystem":"npm"}