npm package: @hybrbase/stylelint-config
Description: A shareable stylelint configuration for projects.
Author: Toby Bui
Latest version: 0.0.0

# Shareable Stylelint Config

This npm package provides a set of shareable configurations for [Stylelint](https://stylelint.io/) 15+ — a linter for CSS and SCSS.

<br>

## 📄 About

Collection of stylelint configurations that can be used to enforce consistent styling across CSS and SCSS files.

The configurations provided in this package are designed to be flexible and easily extendable, allowing developers to customize the rules to fit their specific needs.

### → Purpose

Provide a set of opinionated yet flexible configurations for stylelint that help developers to maintain consistent code styling and avoid common errors. The configurations provided in this package:

- Provide a solid foundation for a project's code styling that can be extended and modified as needed
- Enforce common best practices for CSS and SCSS development, such as using consistent indentation, avoiding vendor prefixes, and avoiding unnecessary specificity
- Catch common errors, such as missing units for numeric values, using invalid colors, and using unsupported or deprecated CSS features
- Help developers to maintain consistency across their codebase by providing clear and consistent rules for code styling.

<br>

## 💿 Installation

To use `@hybrbase/stylelint-config` in an app that uses CSS or SCSS, you need to install `stylelint` and `@hybrbase/stylelint-config` in the app's directory within the monorepository.

For example, if you have a Next.js app located in `apps/web`, you would install `stylelint` and `@hybrbase/stylelint-config` in the `apps/web` directory using the following command:

```bash
pnpm --filter=web add -D stylelint @hybrbase/stylelint-config
```

<br>

## 💻 Usage

You can use one of the provided configurations by adding it to your `stylelint` configuration file.

For example, to use the `@hybrbase/stylelint-config/scss` configuration for your Next.js app, add the following to your `apps/web/.stylelintrc.js` file:

### → CSS

```js
module.exports = {
  extends: '@hybrbase/stylelint-config/css',
}
```

### → SCSS

```js
module.exports = {
  extends: '@hybrbase/stylelint-config/scss',
}
```

You can also customize the rules provided in the configurations or create your own configuration that extends one of the provided configurations. For more information on how to configure `stylelint`, see the [stylelint configuration documentation](https://stylelint.io/user-guide/configure).

### → Extending

You can extend one of the provided configurations in `@hybrbase/stylelint-config` by adding an `overrides` section to your `stylelint` configuration file. For example, to use a mixed CSS/SCSS configuration that ignores files in the `dist` directory, add the following to your `apps/web/.stylelintrc.js` file:

```js
module.exports = {
  ignoreFiles: ['dist/**'],
  extends: '@hybrbase/stylelint-config/scss',
  overrides: [
    {
      files: ['**/*.css'],
      extends: '@hybrbase/stylelint-config/css',
    },
  ],
}
```

This configuration will extend the `@hybrbase/stylelint-config/scss` configuration for SCSS files and the `@hybrbase/stylelint-config/css` configuration for CSS files, and will ignore all files in the `dist` directory.

### → Add a NPM Script

To add an NPM script for running `stylelint` use command, which will add the `lint:styles` script to the `scripts` section of your `package.json`.

```bash
# pnpm pkg set scripts.lint:styles="stylelint --fix **/*.{css,scss}"
```

This will run `stylelint` on all CSS and SCSS files in your app's directory and its subdirectories. You can customize the files and directories to be linted as needed.

## 🚗 Under The Hood

Under the hood, these configurations include various plugins and extends to enforce a range of best practices and standards for CSS and SCSS development.

### `css.js`

- **Plugins**
  - `stylelint-order`
  - `stylelint-no-unsupported-browser-features`
  - `stylelint-high-performance-animation`
- **Extends**
  - `stylelint-config-standard`
  - `stylelint-a11y`

### `scss.js`

- **Plugins**
  - `stylelint-order`
  - `stylelint-no-unsupported-browser-features`
  - `stylelint-high-performance-animation`
- **Extends**
  - `stylelint-config-standard-scss`
  - `stylelint-config-sass-guidelines`
  - `stylelint-a11y`

<br>