@bitfactory/stylelint-config/docs/02-configuration.md

Stylelint sharable config for Bitfactory NL (part of NOBEARS) projects

# Configuration

> [!IMPORTANT]
> **v6.3.0+**: Supports both ES modules (ESM) and CommonJS.
>
> Use `.mjs` config files for ESM or traditional `.js`/`.cjs` files for CommonJS.

## Configuration Examples

### Base CSS

```js
// stylelint.config.mjs
export default {
    extends: ['@bitfactory/stylelint-config'],
};
```

### PostCSS (includes Vue support)

```js
// stylelint.config.mjs
export default {
    extends: ['@bitfactory/stylelint-config/postcss'],
};
```

### SCSS (includes Vue support)

```js
// stylelint.config.mjs
export default {
    extends: ['@bitfactory/stylelint-config/scss'],
};
```

### SASS

```js
// stylelint.config.mjs
export default {
    extends: ['@bitfactory/stylelint-config/sass'],
};
```

### Tailwind CSS (includes Vue support)

**For Tailwind CSS v3:**

```js
// stylelint.config.mjs
export default {
    extends: ['@bitfactory/stylelint-config/tailwind'],
};
```

**For Tailwind CSS v4:**

```js
// stylelint.config.mjs
export default {
    extends: ['@bitfactory/stylelint-config/tailwindcss'],
};
```

## Vue 3 Enhanced Features

For Vue 3 enhanced features (`:deep()`, `v-bind()`, etc.) with CSS Modules / style tag usage, add `stylelint-config-recommended-vue` to your configuration:

```js
// stylelint.config.mjs
export default {
    extends: [
        '@bitfactory/stylelint-config/postcss', // or '/scss' or '/tailwind' or '/tailwindcss'
        'stylelint-config-recommended-vue',
    ],
};
```

## Custom Configuration

### Overriding Rules

```js
// stylelint.config.mjs
export default {
    extends: ['@bitfactory/stylelint-config'],
    rules: {
        'color-hex-length': 'long',
        'selector-max-id': 2,
    },
};
```

### Turning Off Rules

```js
// stylelint.config.mjs
export default {
    extends: ['@bitfactory/stylelint-config'],
    rules: {
        'declaration-no-important': null,
    },
};
```

### Disabling Rules Inline

```css
.selector {
    color: #fff !important; /* stylelint-disable-line declaration-no-important */
}
```

More about disabling rules: [Stylelint documentation](https://stylelint.io/user-guide/ignore-code/)

## Module Format Support

This package supports both **ES Modules (ESM)** and **CommonJS** formats:

### ESM (Recommended)

Use `.mjs` or `.js` files with `"type": "module"` in your `package.json`:

```js
// stylelint.config.mjs or .stylelintrc.mjs
export default {
    extends: ['@bitfactory/stylelint-config'],
};
```

### CommonJS (Legacy)

Use `.cjs` or `.js` files (without `"type": "module"`):

```js
// .stylelintrc.cjs or .stylelintrc.js
module.exports = {
    extends: ['@bitfactory/stylelint-config'],
};
```

## SCSS vs SASS Naming Patterns

The `scss` and `sass` configs use **different naming pattern strategies**:

### SCSS Config (Strict)

Uses **strict kebab-case** patterns from `stylelint-config-standard-scss`:

- Functions: `^(-?[a-z][a-z0-9]*)(-[a-z0-9]+)*$`
  - Examples: `get-color`, `calculate-width`
- Variables: Must be kebab-case
  - Examples: `$primary-color`, `$font-size`

### SASS Config (Permissive)

Uses **permissive patterns** allowing numbers at the end:

- Functions: `^[a-z]+([a-z0-9-]+[a-z0-9]+)?$`
  - Examples: `get-color2`, `calculate-width3`
- Variables: Allows leading underscore
  - Examples: `$_private-var`, `$font-size2`

Choose based on your project's naming conventions. Both are valid approaches.