Personal-style-guide NPM

💡 Motivation

Consistency in code style is key to maintaining scalable and maintainable projects. While many tools like ESLint, Prettier, and Stylelint exist, configuring them repeatedly across projects can be tedious and error-prone. This package centralizes the configuration for these tools, saving time and ensuring a unified development experience across all Didor projects.

This style guide also promotes best practices.

🚀Getting Started

Prerequisites

ESLint, Prettier, Stylelint, Typescript are a peer dependency, so you need to install at the root of your project:

npm install --save-dev eslint prettier stylelint typescript

Installation

To install the package, run:

npm install --save-dev personal-style-guide

ESLint

Plugins Integrated

@eslint/js: JavaScript linting rules.
typescript-eslint: TypeScript linting rules.
eslint-plugin-n: Node.js specific rules.
eslint-plugin-import: Import validation and sorting.
eslint-plugin-security: Detects security issues.
eslint-plugin-perfectionist: Code organization rules.
eslint-plugin-unicorn: Advanced JS/TS best practices.
eslint-plugin-tsdoc: TSDoc comment validation.
eslint-plugin-eslint-comments: ESLint comment rules.
eslint-import-resolver-typescript: TypeScript import resolver.

How to Use

You need to extend one or both of the following configurations.

personal-style-guide/eslint/browser for browser projects.
personal-style-guide/eslint/node for Node projects.

Create or update eslint.config.js in your project root and extend the configurations you need:

import eslintNode from "personal-style-guide/eslint/node";

export default [...eslintNode];

Prettier

How to Use

To use the shared Prettier config, create or update .prettierrc.config.js in your project root:

export { default } from "personal-style-guide/prettier/index.js";

If you need to extend the configuration, you can do so:

import prettierConfig from "personal-style-guide/prettier/index.js";

export default {
  ...prettierConfig,
  ...
};

Why We Don't Use Prettier with ESLint or Stylelint

To improve IDE performance and avoid redundant processing, we separate the responsibilities of Prettier and linters (ESLint/Stylelint):

ESLint and Stylelint: Focus only on code validation and enforcing rules.
Prettier: Handles code formatting exclusively.

By not integrating Prettier directly into ESLint or Stylelint:

Faster IDE Performance: Linters don’t need to process formatting errors, reducing overhead.
Avoid Duplicated Tasks: Prevent running the file through both a linter and Prettier simultaneously.

Stylelint

Plugins Integrated

stylelint-config-recommended: Recommended stylelint rules.
stylelint-config-recommended-scss: Recommended SCSS stylelint rules.
stylelint-config-recommended-vue: Recommended Vue stylelint rules.
stylelint-config-recess-order: Recess order stylelint rules.

How to Use

Create or update stylelint.config.js in your project root:

module.exports = {
  extends: ["personal-style-guide/stylelint"],
};

TypeScript

How to Use

This style guide provides multiple TypeScript configs. These configurations are based on the environment you are working on, so you need to extend one of the following configurations:

personal-style-guide/typescript/node.
personal-style-guide/typescript/browser.

Ensure you have a tsconfig.json in your project root. You can extend the provided configuration if necessary:

{
  "extends": "personal-style-guide/typescript/node"
}

Markdown

⚠️ Note: This configuration is designed for markdownlint. Install the Markdownlint extension in your editor (e.g., VS Code) for optimal use.

How to Use

To lint Markdown files, extend the provided configuration by creating or updating a .markdownlint.json file in your project root:

{
  "extends": "personal-style-guide/markdown"
}


## 📑 Scripts

Add the following scripts to your `package.json` to lint and format your code:

```json
{
  "scripts": {
    "lint:js": "eslint 'src/**/*.{js,ts,vue}'",
    "lint:css": "stylelint 'src/**/*.{scss,css}'",
    "format": "prettier --write 'src/**/*.{js,ts,vue,scss,css}'"
  }
}

🔄 Updating

To check for outdated dependencies, run:

npx npm-check-updates

This lists all outdated dependencies. It's important to read the release notes for each dependency to understand the changes.

Update dependencies running the interactive mode. It's recommended to update them one by one to avoid breaking changes.:

npx npm-check-updates --interactive

🗺️ Roadmap

Add configurations for testing frameworks (e.g., Jest, Vitest).
Add configurations for Vue and Nuxt projects.
Improve the ESLint configuration to group by file type.
Add @eslint/json and @eslint/markdown configurations to the ESLint setup.

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository.
Create a new branch (git checkout -b feature/my-feature).
Make your changes and write tests.
Commit your changes using a conventional commit message.
Push your branch and open a Pull Request.

📜 License

This template is licensed under the MIT License, which allows you to use, modify, and distribute the code freely, as long as the original license is included.

For more details, see the LICENSE file included in this repository.