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-client-check

v1.1.0

Published

ESLint plugin to ensure safe usage of client-side globals in isomorphic code.

Downloads

4

Readme

eslint-plugin-client-check

An ESLint plugin designed to enforce safe usage of client-side globals like window, document, and others. This plugin ensures that these globals are properly checked before being used in your code, helping to prevent errors when running JavaScript in environments where these globals may not be available, such as during server-side rendering (SSR) or in non-browser environments.

Table of Contents

Installation

Prerequisites

Ensure you have ESLint installed in your project:

npm install eslint --save-dev

Then, install the eslint-plugin-client-check plugin:

npm install eslint-plugin-client-check --save-dev

Usage

To start using the eslint-plugin-client-check plugin, add it to your ESLint configuration file (.eslintrc, .eslintrc.json, or .eslintrc.js).

Basic Setup

Add client-check to the plugins array and enable the no-unsafe-client-side-usage rule:

{
  "plugins": ["client-check"],
  "rules": {
    "client-check/no-unsafe-client-side-usage": "error"
  }
}

Configuration

Rule Details

The no-unsafe-client-side-usage rule enforces that certain global variables, which are only available in the browser environment, are checked for existence before being used in your code. This prevents runtime errors in non-browser environments or during SSR.

Globals Checked by Default

The rule checks for the following client-side globals by default:

  • window
  • document
  • navigator
  • location
  • history
  • localStorage
  • sessionStorage
  • fetch
  • performance
  • screen

Examples

Correct Usage

Below are examples of code that passes the no-unsafe-client-side-usage rule.

Example 1: Using typeof to Check for window

if (typeof window !== 'undefined') {
  window.addEventListener('resize', () => {
    console.log('Window resized');
  });
}

Example 2: Using a Truthy Check for window

if (window) {
  console.log('Window exists');
}

Example 3: Compound Condition with typeof

if (typeof document !== 'undefined' && typeof window !== 'undefined') {
  document.addEventListener('click', () => {
    console.log('Document clicked');
  });
}

Example 4: Checking for window in globalThis

if ('window' in globalThis) {
  console.log('Window exists in globalThis');
}

Incorrect Usage

Below are examples of code that will trigger the no-unsafe-client-side-usage rule.

Example 1: Using window Without a Check

window.addEventListener('resize', () => {
  console.log('Window resized');
});

Example 2: Using document Without a Check

document.getElementById('app').innerHTML = 'Hello, World!';

These examples will result in ESLint errors, prompting you to add the necessary checks.

Advanced Configuration

Customizing Restricted and Additional Globals

By default, the plugin checks the most common client-side globals. However, you can customize the list of globals to suit your specific project needs, including adding your own custom globals that you want to enforce checks on.

Example: Adding Custom Globals

If you want to add a new global (e.g., myCustomGlobal) to the list of restricted globals, you can modify the plugin configuration like this:

{
  "plugins": ["client-check"],
  "rules": {
    "client-check/no-unsafe-client-side-usage": ["error", {
      "additionalGlobals": ["myCustomGlobal"]
    }]
  }
}

In this example, myCustomGlobal is added to the list of globals that the rule will check. You can also remove or override the default globals by specifying them explicitly under restrictedGlobals.

Example: Adding and Removing Globals

{
  "plugins": ["client-check"],
  "rules": {
    "client-check/no-unsafe-client-side-usage": ["error", {
      "restrictedGlobals": [
        "window",
        "document",
        // Remove any globals you don't want to check
        // "navigator"
      ],
      "additionalGlobals": [
        "myCustomGlobal"
      ]
    }]
  }
}

FAQs

Why do I need this plugin?

This plugin is essential for projects that involve server-side rendering (SSR) or environments where certain globals (like window or document) might not be available. It helps prevent runtime errors by enforcing safe checks before these globals are used.

Does this plugin support TypeScript?

Yes, this plugin works with TypeScript projects. Just make sure your ESLint setup is configured to parse TypeScript files.

What if I don't want to enforce all the checks?

You can customize which globals are checked by modifying the restrictedGlobals and additionalGlobals options as shown in the Advanced Configuration section.

Contributing

Contributions are welcome! If you find a bug or have a feature request, please open an issue on the GitHub repository.

If you'd like to contribute code, feel free to submit a pull request. Please ensure that your code adheres to the existing coding standards and includes tests for any new functionality.

License

This project is licensed under the MIT License. See the LICENSE file for details.