Additional Information

Linter Extensions

Linter extensions are additional packages or plugins that extend the functionality of base linter tools that Qlty uses. Depending on the linter, extensions can add:

  • Additional rule sets
  • Custom rules
  • Language support
  • Framework-specific checks
  • Additional parsers

For example, ESLint has numerous plugins like eslint-plugin-react, eslint-plugin-security, and eslint-plugin-jest that add specialized rules for React development, security checks, and Jest testing, respectively.

Supported Package Managers

Qlty supports linter extensions through the following package managers:

  • NPM (Node.js) - For JavaScript/TypeScript tools like ESLint, Stylelint, etc.
  • RubyGems (Ruby) - For Ruby tools like RuboCop, Standard, etc.
  • PIP (Python) - For Python tools like Ruff, Pylint, Bandit, etc.
  • Composer (PHP) - For PHP tools like PHP_CodeSniffer, PHPStan, etc.

Managing linter extensions

Qlty provides two mutually exclusive ways to configure linter extensions in your qlty.toml file: extra_packages and package_file.

extra_packages

The extra_packages property allows you to explicitly list additional packages that should be installed alongside the main linter package (including their versions).

qlty.toml
1[[plugin]]
2name = "eslint"
3version = "8.57.0"
4extra_packages = [
5  "eslint-plugin-react@7.33.2",
6  "eslint-plugin-jest@27.6.0"
7]

Pros:

  • Simple, direct specification
  • Version pinning
  • Works without existing package files

Cons:

  • Duplicate dependency management
  • May diverge from project dependencies

package_file

The package_file property allows you to reference a package manager file (like package.json or Gemfile) to manage dependencies. Depending on your use case, you can point the package_file either at your project’s main package file or at a specific file that contains the linter-related packages.

1[[plugin]]
2name = "eslint"
3version = "8.57.0"
4package_file = "package.json"

Pros:

  • Take advantage of package manager’s dependency resolution
  • Consistent with project dependencies (if pointing to the main package file)

Cons:

  • Project’s main package file contains many dependencies

package_filters

When using package_file, you can use package_filters to selectively include only specific packages from the package file. This will cause Qlty to filter the packages in the package file and only install the ones that match the filters.

This is most useful when you are pointing the package_file directive to your project’s main package file, and you want to install only the linter-related packages. This can be used to speed up the installation of linters.

qlty.toml
1[[plugin]]
2name = "eslint"
3version = "8.57.0"
4package_file = "package.json"
5package_filters = ["eslint"]

The package_filters option can offer a performance speed up or workaround issues installing the app dependencies at the tradeoff of additional complexity.

Lock files

Package lock files (like package-lock.json, Gemfile.lock, yarn.lock) can impact how Qlty installs and manages linter extensions:

  • When using package_file, Qlty respects the locked versions for reliability
  • When using package_file with package_filters, the lock files are ignored
  • For extra_packages, lock files are not used and specific versions are installed directly

Custom RuboCop cops

Qlty supports using in-repository Rubocop custom cops - custom rules defined within your codebase, which are referenced in your .rubocop.yml config file.

Names of any such related files need to be added to plugin config. Otherwise you may get an error like cannot load such file -- /tmp/qlty/qEYkEfFX-rw/./path/to/local/file

1[[plugin]]
2name = rubocop
3config_files = ["custom_cop.rb"] # files names of custom configuration files, not paths

Limitations

Qlty currently does not support:

  • Private linter extensions - Extensions from private Git repositories or private package registries that require authentication
  • Git-based dependencies - Extensions referenced directly as Git repositories
  • Local file dependencies outside the repository - Extensions referenced from paths outside the repository

Troubleshooting

  1. Version conflicts

    If you see errors like “Dependency conflict” or “Incompatible versions”, try:

    • Aligning versions between your package file and extra_packages
    • Using package_filters to selectively include compatible packages

  2. Missing extensions

    If a linter reports missing plugins or rules:

    • Verify the extension is correctly specified in extra_packages or package_file.
    • Check for typos in package names.
    • Ensure compatible versions are specified.

  3. Slow performance

    If linter installation becomes slow with extensions:

    • Use either package_filters to filter installations, or create a separate package file for linter-related packages.

  4. Configuration issues

    If the linter can’t find the extension configuration:

    • Ensure your configuration file correctly references the extensions.
    • Check that the extension is properly installed.