@heavy-dev/config/README.md

Shared configuration files for Heavy Dev projects

# Heavy Dev Config

A shared set of configuration files for Heavy Dev projects, including Prettier, ESLint, Tailwind, VSCode, and TypeScript configurations.

## Installation

To install the configuration, run:

```bash
npm install --save-dev @heavy-dev/config
```

## Usage

### Prettier

#### Extending the Prettier Configuration

If you want to use the shared Prettier configuration but also add project-specific settings (e.g., plugins or overrides), you can extend it in your `.prettierrc.js` file.  It is recommended to use a `.prettierrc.js` as opposed to `json`.  This allows us to use additional plugins and create local overrides if necessary.  `.vscode/settings.json` is set up to point to `.prettierrc.js` for Prettier configurations.

#### Example:

Create a `.prettierrc.js` file in your project root with the following content:

```javascript
module.exports = {
  ...require("@heavy-dev/config/prettier.json"),
  // plugins and overrides here. For example:
  plugins: ["prettier-plugin-tailwindcss"],
};
```

#### Settings:

- **`semi`**: Adds semicolons at the end of statements (`true`).
- **`singleQuote`**: Uses single quotes instead of double quotes (`true`).
- **`trailingComma`**: Adds trailing commas wherever possible (`all`).
- **`printWidth`**: Sets the maximum line length for better readability (`80`).
- **`tabWidth`**: Uses 2 spaces per indentation level (`2`).
- **`arrowParens`**: Always includes parentheses around arrow function parameters (`always`).
- **`jsxSingleQuote`**: Uses double quotes in JSX attributes (`false`).
- **`bracketSpacing`**: Adds spaces inside object literal braces (`true`).
- **`endOfLine`**: Uses LF (Line Feed) for line endings (`lf`).
- **Overrides**:
  - Applies the TypeScript parser for `.ts` and `.tsx` files.

### ESLint
1. Install the required dependencies:
```bash
npm install --save-dev eslint eslint-plugin-simple-import-sort @typescript-eslint/eslint-plugin @typescript-eslint/parser
```
2. Create `eslint.config.mjs` at your project root.
> **Note**: It is now recommended to use `eslint.config.mjs` instead of `eslint.json` for ESLint configuration. This allows for more flexibility, such as using JavaScript features like `import` and dynamic configuration. For more details, see the [ESLint Migration Guide](https://eslint.org/docs/latest/use/configure/migration-guide).

3. Extend the configuration in your  or `eslint.config.mjs`:

```js
// eslint.config.mjs
import { FlatCompat } from "@eslint/eslintrc";

const compat = new FlatCompat({
  baseDirectory: import.meta.url,
});

export default [
  ...compat.extends("./node_modules/@heavy-dev/config/eslint.json"),
];
```

3. Optional: Add an ESLint script to your package.json:

```bash
{
  {
    "scripts": {
      "lint": "eslint . --ext .js,.jsx,.ts,.tsx"
  }
}
```
4. Run ESLint:
```bash
npm run lint
```

### TypeScript

To use the shared TypeScript configuration, extend it in your project's `tsconfig.json` file. This allows you to inherit the base configuration while adding or overriding specific settings for your project.

#### Steps to Use

1. **Extend the configuration in your tsconfig.json:**

```json
  {
    "extends": "@heavy-dev/config/tsconfig.json",
    "compilerOptions": {
      "baseUrl": ".", // Example of a project-specific override
      "paths": {
        "@components/*": ["./src/components/*"] // Example of custom path aliases
      }
    },
    "include": ["src/**/*"], // Include your project's source files
    "exclude": ["node_modules"] // Exclude unnecessary files
  }
```

### VS Code Configuration

This package includes a shared `.vscode` directory with recommended settings, extensions and Tailwind configuration for Heavy Dev projects.

#### Usage

1. Copy or symlink the .vscode directory:

  To copy:
  ```bash
    cp -r node_modules/@heavy-dev/config/.vscode .vscode
  ```

  To symlink:
  ```bash
    ln -s node_modules/@heavy-dev/config/.vscode .vscode
  ```

#### Included Settings

- **`css.customData`**: Points to the `tailwind.json` file for enhanced Tailwind CSS IntelliSense.
- **`prettier.requireConfig`**: Ensures Prettier uses a configuration file for formatting.
- **`prettier.prettierPath`**: Specifies the path to the Prettier package in `node_modules`.
- **`prettier.configPath`**: Points to the `.prettierrc.js` file for Prettier configuration.
- **`editor.formatOnSave`**: Automatically formats files on save.
- **`editor.defaultFormatter`**: Sets Prettier as the default formatter for various file types:
  - **JavaScript** (`[javascript]`)
  - **React (JSX)** (`[javascriptreact]`)
  - **TypeScript** (`[typescript]`)
  - **React (TSX)** (`[typescriptreact]`)
  - **HTML** (`[html]`)
  - **CSS** (`[css]`)
  - **JSON** (`[json]`)

These settings ensure consistent formatting and improved IntelliSense for Tailwind CSS and Prettier across your project.

#### Recommended Extensions

- **[Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)**: Code formatter (`esbenp.prettier-vscode`).
- **[ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)**: Linter for JavaScript/TypeScript (`dbaeumer.vscode-eslint`).
- **[TypeScript Nightly](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-typescript-next)**: Latest TypeScript features (`ms-vscode.vscode-typescript-next`).

#### Tailwind IntelliSense Configuration

The `css.customData` setting points to the `tailwind.json` file, which enhances the Tailwind CSS development experience in VS Code. It provides IntelliSense support for Tailwind directives, making it easier to write and understand Tailwind CSS in your projects.

To ensure this works, install the **[Tailwind CSS IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss)** extension in VS Code.

This package includes a `tailwind.json` file to enhance the Tailwind CSS development experience in VS Code. It provides IntelliSense support for Tailwind directives, making it easier to write and understand Tailwind CSS in your projects.

#### Supported `@` Directives

- **`@tailwind`**: Inserts Tailwind's `base`, `components`, `utilities`, and `screens` styles into your CSS.
  - [Documentation](https://tailwindcss.com/docs/functions-and-directives#tailwind)

- **`@apply`**: Inlines existing utility classes into custom CSS, useful for extracting common utility patterns.
  - [Documentation](https://tailwindcss.com/docs/functions-and-directives#apply)

- **`@responsive`**: Generates responsive variants of custom classes by wrapping their definitions in the `@responsive` directive.
  - Example:
    ```css
    @responsive {
      .alert {
        background-color: #E53E3E;
      }
    }
    ```
  - [Documentation](https://tailwindcss.com/docs/functions-and-directives#responsive)

- **`@screen`**: Creates media queries referencing breakpoints by name instead of duplicating their values.
  - Example:
    ```css
    @screen sm {
      /* ... */
    }
    ```
    Transforms into:
    ```css
    @media (min-width: 640px) {
      /* ... */
    }
    ```
  - [Documentation](https://tailwindcss.com/docs/functions-and-directives#screen)

- **`@variants`**: Generates variants like `hover`, `focus`, and `active` for custom utilities.
  - Example:
    ```css
    @variants hover, focus {
      .btn-brand {
        background-color: #3182CE;
      }
    }
    ```
  - [Documentation](https://tailwindcss.com/docs/functions-and-directives#variants)

#### How to Use

1. Ensure you have the [Tailwind CSS IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss) extension installed in VS Code.
2. The [tailwind.json](http://_vscodecontentref_/1) file will automatically provide descriptions and references for Tailwind directives as you type.

This configuration helps streamline your workflow by providing detailed descriptions and links to documentation directly in your editor.

## Updating the Package
If you make changes to the configuration, update the version in package.json (e.g., from 1.0.0 to 1.0.1) and run:

```bash
npm publish
```