npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

eslint-plugin-square

v26.0.0

Published

Linting plugin containing Square's custom lint rules and configuration for JavaScript and related technologies.

Downloads

6,436

Readme

eslint-plugin-square

npm version CI

This plugin contains lint rule definitions and configurations for ESLint specific to Square's needs. It serves mainly to consolidate Square's web frontend linting setup in one place. It is generally not recommended for public usage outside of Square.

Requirements

Usage

Install alongside ESLint via yarn (or npm):

yarn add --dev eslint eslint-plugin-square npm-run-all

If you're creating a new ESLint configuration, refer to ESLint's documentation to determine the correct file format for your project. For example, ESM projects with "type": "module" in their package.json should use an .eslintrc.cjs file format instead of .eslintrc.js.

Once you have an ESLint configuration file, add this plugin to your extends property:

module.exports = {
  extends: ['plugin:square/base'], // Or other configuration.
};

Add the relevant lint scripts in package.json with npm-run-all and include detection for unused disable directives:

{
  "scripts": {
    "lint": "npm-run-all --continue-on-error --aggregate-output --parallel lint:*",
    "lint:js": "eslint --report-unused-disable-directives --cache ."
  }
}

Configure linting to run:

  • With the ESLint extension for your IDE
  • In your precommit hook (see lint-staged and husky)
  • As a build check during CI (in case IDE warnings or the precommit hook are bypassed)

Fix violations using:

  • Lint rule autofixers (eslint --fix)
  • Lint rule suggestions (a fixer option provided by some rules on highlighted violations in IDEs)
  • Codemods (sometimes provided for larger codebase transformations)
  • Find-and-replace (with RegExp if necessary)
  • Manual fixes

Sometimes, you may not want to fix certain violations, for reasons such as:

  • Some code is too risky to change
  • A rule may have too many violations and fixing is too tedious / manual
  • A rule may have false positives and flag legitimate code
  • A rule may not apply in all circumstances (such as a rule that is only useful for test code)
  • You may prefer to follow different conventions/styles in your codebase
  • You may want to follow-up later to address a specific rule in its own PR

If you prefer not to adopt a specific rule, you can disable it:

  • Globally (in the global configuration file)
  • In specific directories (in an override in the global configuration file)
  • In specific files or on specific lines using comments (// eslint-disable-line no-empty-function)

Configurations

| | Name | Description | | --- | --- | --- | | ✅ | base | Rules and configuration for any JavaScript-based project. Includes recommended and optional rules from eslint, prettier, eslint-plugin-eslint-comments, eslint-plugin-import, eslint-plugin-unicorn, and more. | | 🔥 | ember | Ember.js-specific additions on top of base. Includes recommended and optional rules from eslint-plugin-ember, kebab-case filename enforcement with eslint-plugin-filenames, and more. | | ⚛️ | react | React-specific additions on top of base. Includes recommended rules from eslint-plugin-jsx-a11y, eslint-plugin-react, and eslint-plugin-react-hooks. | | 🔒 | strict | A variety of stricter lint rules on top of base. | | ⌨️ | typescript | TypeScript-specific additions on top of base. Use with @typescript-eslint/parser. |

Rules enabled by these configurations should meet the following criteria:

  • They make sense in a wide variety of codebases (and have been tested in a variety of Square's applications).
  • They are generally acceptable and desirable (in terms of enforcing best practices, consistency, avoiding bugs) to most developers.
  • There is a practical migration path (autofixers, codemod, find-and-replace, manual fixes) for enabling them in most applications.

Custom rules

💼 Configurations enabled in.
🔥 Set in the ember configuration.
🔒 Set in the strict configuration.
🔧 Automatically fixable by the --fix CLI option.
💡 Manually fixable by editor suggestions.

| Name                             | Description | 💼 | 🔧 | 💡 | | :--------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- | :---- | :- | :- | | no-assert-ok-find | disallow usage of assert.ok(find(...)) as it will always pass | 🔥 | | 💡 | | no-handlebar-interpolation | disallow unsafe HTML in strings/hbs/translations | | | | | no-missing-tests | disallow files without a corresponding test file | | | | | no-restricted-files | disallow files with a path matching a specific regexp | | | | | no-test-return-value | disallow test functions with a return value | 🔥 | | 💡 | | no-translation-key-interpolation | disallow string interpolation in translation keys | 🔥 | | | | require-await-function | enforce using await with calls to specified functions | 🔥 | 🔧 | | | use-call-count-test-assert | enforce using assert.equal(...callCount, ...); instead of assert.ok(...calledOnce); | 🔥 🔒 | 🔧 | | | use-ember-find | require use of Ember's find helper instead of jQuery for selecting elements in tests | 🔥 | 🔧 | |

Note that we prefer to upstream our custom lint rules to third-party ESLint plugins whenever possible. The rules that still remain here are typically here because:

  • We haven't found the appropriate ESLint plugin to upstream them to.
  • We haven't found the time to upstream them.
  • They are specific to Square in some way / not generic enough.

If you do need to write a custom lint rule here because you can't find an existing lint rule to use or other ESLint plugin to contribute to, be sure to consult astexplorer.net while writing it.

Lint rule ideas often come from:

  • A source of frequent "nit" comments in PRs
  • Common issues that newcomers stumble on
  • Code that indicates a bug, mistake, or bad practice
  • Inconsistencies throughout the codebase
  • Outdated / obsolete / legacy code

Related

Consider adding other linters not included by plugin:

License

Copyright 2020 Square Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.