{"id":13068,"library":"depcheck","title":"Depcheck","description":"Depcheck is a widely used command-line interface (CLI) tool and programmatic library for analyzing Node.js project dependencies. Its primary function is to identify unused dependencies, detect missing dependencies required by the codebase, and provide insights into how declared dependencies are actually utilized. The current stable version is 1.4.7. While not adhering to a strict release schedule, the project is actively maintained, with multiple patch releases in 2023 and 2021, and significant updates including a breaking change in 2020 (v1.3.x). A key differentiator for Depcheck is its extensive syntax support, covering not only standard JavaScript (ES5-ES7) and React JSX but also CoffeeScript, TypeScript, SASS/SCSS, and Vue.js. Furthermore, it includes 'special' components designed to recognize dependencies used within various configuration files for tools like Babel, ESLint, Webpack, Jest, and Serverless, moving beyond basic `import` or `require` statements. This comprehensive analysis helps developers maintain leaner, more efficient codebases by facilitating the removal of unnecessary packages, which can improve performance and reduce bundle sizes.","status":"active","version":"1.4.7","language":"javascript","source_language":"en","source_url":"git://github.com/depcheck/depcheck","tags":["javascript","check","unused","package","packages","depcheck","dependency","dependencies","devDependencies","typescript"],"install":[{"cmd":"npm install depcheck","lang":"bash","label":"npm"},{"cmd":"yarn add depcheck","lang":"bash","label":"yarn"},{"cmd":"pnpm add depcheck","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for parsing TypeScript files.","package":"typescript","optional":false},{"reason":"Required for parsing Vue.js Single File Components.","package":"@vue/compiler-sfc","optional":false}],"imports":[{"note":"The primary export is a default function (or CommonJS module.exports), which is typically imported directly or via `require`. Named imports are incorrect for the main function.","wrong":"import { depcheck } from 'depcheck';","symbol":"depcheck","correct":"import depcheck from 'depcheck';\n// Or for CommonJS:\n// const depcheck = require('depcheck');"},{"note":"TypeScript types for options and results are available as named exports prefixed with 'Options' and 'Results' respectively, but should be imported as types to avoid runtime issues if not tree-shaken.","wrong":"import { DepcheckOptions } from 'depcheck';","symbol":"DepcheckOptions","correct":"import type { Options as DepcheckOptions, Results as DepcheckResults } from 'depcheck';"},{"note":"When imported programmatically, advanced configurations like custom parsers are accessed as properties on the main 'depcheck' function, e.g., `depcheck.parser.jsx`.","symbol":"depcheck.parser","correct":"import depcheck from 'depcheck';\n// ... then access parsers via depcheck.parser.jsx or similar"}],"quickstart":{"code":"import depcheck from 'depcheck';\nimport path from 'path';\n\ninterface DepcheckResults {\n  dependencies: string[];\n  devDependencies: string[];\n  missing: { [key: string]: string[] };\n  using: { [key: string]: string[] };\n  invalidDirs: { [key: string]: string };\n  invalidFiles: { [key: string]: string };\n}\n\nasync function runDepcheck(projectRoot: string): Promise<void> {\n  const options = {\n    ignoreBinPackage: false, // ignore the packages with bin entry\n    skipMissing: false, // skip calculation of missing dependencies\n    json: true, // output results in JSON format\n    ignorePatterns: [\n      'dist', // ignore build output directory\n      'coverage', // ignore coverage directory\n      '*.log' // ignore log files\n    ],\n    // Add 'typescript' if you have TypeScript files and it's not a direct dependency\n    // 'parsers': { '*.ts': depcheck.parser.typescript },\n    // 'specials': [depcheck.special.eslint, depcheck.special.webpack] // example specials\n  };\n\n  try {\n    const results: DepcheckResults = await depcheck(projectRoot, options) as any; // Cast to any due to programmatic type nuances\n\n    if (results.dependencies.length > 0) {\n      console.log('Unused dependencies:', results.dependencies);\n    }\n    if (results.devDependencies.length > 0) {\n      console.log('Unused devDependencies:', results.devDependencies);\n    }\n    if (Object.keys(results.missing).length > 0) {\n      console.log('Missing dependencies:', results.missing);\n    }\n    if (Object.keys(results.using).length > 0) {\n      console.log('Dependencies in use (example):', Object.keys(results.using).slice(0, 2));\n    }\n    if (results.dependencies.length === 0 && results.devDependencies.length === 0 && Object.keys(results.missing).length === 0) {\n      console.log('No depcheck issues found for this project.');\n    }\n  } catch (error) {\n    console.error('Depcheck encountered an error:', error);\n  }\n}\n\n// Example usage: Point to a dummy project root (create a package.json and some files)\n// In a real scenario, this would be your actual project directory.\nconst dummyProjectRoot = path.resolve(process.cwd(), 'temp-depcheck-project');\nconsole.log(`Running depcheck in: ${dummyProjectRoot}`);\n\n// Create a dummy package.json and an index.ts/js to simulate a project\n// This part would typically be part of your project setup, not quickstart code.\n// For demonstration, assume a basic project structure already exists.\n\n// To make this runnable, ensure a 'temp-depcheck-project' exists with a package.json\n// Example setup:\n// mkdir temp-depcheck-project\n// cd temp-depcheck-project\n// echo '{ \"name\": \"test-project\", \"version\": \"1.0.0\", \"dependencies\": { \"lodash\": \"^4.17.21\" }, \"devDependencies\": { \"jest\": \"^29.0.0\" } }' > package.json\n// echo 'import { get } from \"lodash\"; console.log(get({}, \"a\"));' > index.js\n// echo 'const sum = require(\"non-existent-pkg\");' > another.js\n// npm install\n\nrunDepcheck(process.cwd()); // Or specify a relative path to your project","lang":"typescript","description":"This quickstart demonstrates how to programmatically execute `depcheck` on a project directory, capturing and logging its findings regarding unused, missing, and used dependencies in JSON format. It highlights common configuration options for ignoring specific files or directories and provides a basic structure for handling results."},"warnings":[{"fix":"Update your `.depcheckrc` or programmatic `options.parsers` configuration to use `**/*.js` (or similar) instead of `*.js` for glob patterns.","message":"The configuration for custom parsers changed significantly in versions 1.3.0 and 1.3.1. If you use `depcheck` programmatically or via a configuration file, the `parsers` key syntax shifted from using single asterisk `*.js` to double asterisk `**/*.js` glob patterns.","severity":"breaking","affected_versions":">=1.3.0 <1.4.0"},{"fix":"Run `npm install --save-dev typescript @vue/compiler-sfc` (or `yarn add -D typescript @vue/compiler-sfc`) in your project root to ensure these peer dependencies are available to `depcheck`.","message":"For `depcheck` to properly analyze TypeScript or Vue.js files, you must explicitly install the `typescript` and/or `@vue/compiler-sfc` packages as dependencies in your project, even if they are already present as devDependencies. `depcheck` relies on these external packages for syntax support.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Utilize the `--ignores` CLI option or the `ignore` property in a `.depcheckrc` configuration file to explicitly tell `depcheck` to disregard specific packages that are validly used but misidentified as unused. For directories, use `--ignore-patterns`.","message":"Depcheck can produce 'false positives' for dependencies that are used indirectly, dynamically, or within specific configuration files (e.g., Jest typings, ESLint plugins, Webpack loaders) not fully covered by its 'special' component logic. While many common cases are handled, complex setups may require manual intervention.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your project's Node.js environment is version 10 or newer. Use a Node.js version manager like `nvm` to switch to a compatible version.","message":"Depcheck requires Node.js version 10 or higher. Running it with older Node.js versions will result in execution errors or unexpected behavior.","severity":"gotcha","affected_versions":"<1.0.0"},{"fix":"Consider running `depcheck` within each sub-project directory or configure it to `--ignore-patterns` that contain other `package.json` files. Tools like `lerna` or `nx` often provide mechanisms to run scripts like `depcheck` across individual packages.","message":"When working in monorepos or projects with multiple `package.json` files, `depcheck` might incorrectly report dependencies as unused if it doesn't correctly resolve imports across sub-projects or local packages. Running `depcheck` from the root may not capture all nuances of nested `package.json` files.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Verify that your `tsconfig.json` `paths` and `package.json` `imports` configurations are standard and well-formed. If issues persist, consider adding problematic paths or modules to the `--ignores` or `ignorePatterns` configuration.","message":"While versions 1.4.7 and later support `package.json` subpath imports, complex aliasing, or TypeScript `paths` configurations can still lead to misidentification of dependencies or parsing failures if not correctly resolved by `depcheck`'s internal mechanisms.","severity":"gotcha","affected_versions":">=1.4.7"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"For ESM, use `import depcheck from 'depcheck';`. For CommonJS, use `const depcheck = require('depcheck');`. Ensure your `tsconfig.json` `esModuleInterop` is enabled for TypeScript.","cause":"Attempting to use `depcheck` programmatically with incorrect import syntax, such as a named import `import { depcheck }` when it is a default export, or using `require()` incorrectly in an ESM context.","error":"TypeError: depcheck is not a function"},{"fix":"Install the missing package(s) using `npm install --save-dev typescript @vue/compiler-sfc` (or `yarn add -D typescript @vue/compiler-sfc`).","cause":"Depcheck encounters TypeScript or Vue.js files but the necessary compiler/parser packages (e.g., `typescript`, `@vue/compiler-sfc`) are not installed as direct dependencies in the project.","error":"Cannot find module 'typescript' or Cannot find module '@vue/compiler-sfc'"},{"fix":"Add the reported package to the `--ignores` CLI option or the `ignore` array in a `.depcheckrc` configuration file. You can also explicitly enable or configure `specials` via `options.specials` in programmatic use or `parsers` option.","cause":"A dependency is used within a configuration file (like ESLint, Webpack, Jest, Babel) that `depcheck`'s default 'special' component logic doesn't fully cover or is misconfigured.","error":"Depcheck reports 'lodash' as unused, but it's used in my `.eslintrc.js`."},{"fix":"Upgrade `depcheck` to the latest version (`npm install depcheck@latest`) as many parsing issues, including those related to ESM config files and newer TypeScript syntax, have been resolved in recent releases (e.g., `v1.4.3`, `v1.4.4`).","cause":"The project uses modern JavaScript/TypeScript syntax (e.g., top-level `await`, `satisfies` operator) or ESM-only `next.config.js` files that older versions of `depcheck` or its underlying parsers could not handle.","error":"Depcheck fails with 'Unexpected token '.' ' or 'SyntaxError: Cannot use import statement outside a module'"},{"fix":"Use the `--ignore-patterns` CLI option or `ignorePatterns` in a `.depcheckrc` file to exclude large directories (e.g., `dist`, `build`, `generated`) and file types (e.g., `*.log`, `*.tmp`) from the analysis. Ensure `node_modules` is implicitly ignored (which it usually is by default).","cause":"The project contains very large directories (e.g., build outputs, extensive temporary files, large `node_modules` not properly ignored) or has a complex dependency graph that `depcheck` attempts to process unnecessarily.","error":"Depcheck takes a very long time to run or runs out of memory."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"depcheck"}