Ng-config-files NPM

ng-config-files

Offers a standardized set of configuration files tailored specifically for Angular libraries and applications

Configuration files

ng-config-files should be included as a dependency in your npm project.

It will install the necessary linters and checkers for your project:

eslint: for TypeScript files (.ts) and component HTML files
stylelint: for CSS and SCSS files
husky: to check files before each commit, utilizing the following two dependencies: - commitlint: to ensure that commit messages conform to the conventional changelog standard - lint-staged: to run linters before commits
conventional-changelog: for generating changelogs based on conventional commit messages

It additionally offers configuration files that can be referenced using the appropriate command, such as "extends", in the configuration file.

manually copied to the root of your project.

All of these files are stored within the config folder.

.editorconfig

This file is utilized to enforce basic rules regarding indentation, trailing whitespaces, and linefeeds in most Integrated Development Environments (IDEs). In certain IDEs or editors, such as VS Code, you may need to install an extension like "EditorConfig for VS Code" (editorconfig.editorconfig). It's highly recommended to install such plugins or extensions in your preferred IDE or editor.

Copy the file into the root directory of your project

.eslintrc.js

Introducing a fresh configuration file for ESLint, equipped with TypeScript support via TypeScript ESLint and Angular-specific configurations from Angular ESLint.

You can customize and apply this file to your project:

If your project consists solely of JavaScript files (e.g., tools, configuration files), you can remove all TypeScript (.ts) and HTML (.html) related configurations.
Replace the prefix (ng) with the one used in your project, as declared in your angular.json file under project.xxx.prefix.
You can add exclusion patterns to the ignorePatterns array. ESLint will throw errors if it encounters a file not covered by the tsconfig files.
The overrides section divides the options, particularly the rules, between JavaScript, TypeScript (with or without Angular), and HTML files.
In the project array, list the tsconfig files that define the paths to the code to be linted.
In the extends array, specify the configuration files to use for linting your project:
- 'eslint:recommended' for base ESLint rules.
- 'plugin:@typescript-eslint/recommended' for base TypeScript rules.
- 'plugin:@typescript-eslint/recommended-requiring-type-checking' for more advanced TypeScript rules.
- eslintrc.plugins.js defines the plugin configurations (recommended settings and overrides), including angular-eslint configurations.
- eslintrc.semantics.es.js defines ES rules for coding best practices.
- eslintrc.semantics.ts.js extends the ES rules for TypeScript coding best practices.
- eslintrc.style.es.js defines fixable ES rules for code formatting.
- eslintrc.style.ts.js extends the ES rules for TypeScript code formatting.
- eslintrc.html.js defines rules for Angular templates.
- eslintrc.stricter.js contains recommended rules that have been deactivated to remain compatible with existing codebases. You can activate them on new projects or selectively include them in your project's settings.
- eslintrc.demo.js deactivates some rules to be more lenient in demo projects (typically deactivated rules like no-magic-number, no-console, etc.). It can also be used for unit tests.
In the rules section, you can activate or deactivate rules to suit your project's needs.
You can remove the comments marked as TODO, which summarize the aforementioned changes.

Note: If you have a monorepo with multiple projects, each with its own tsconfig, you can place the generic .eslintrc.js file at the top-level and have similar files in each sub-project, overriding the generic one. For instance, in our libraries, there is a generic file for each library and a custom one within the demo_files sub-project, allowing for the definition of specific tsconfig settings and custom rules.

You also need to add or modify the lint section of each project in your angular.json file (located within the architect section) to resemble the following structure:

        "lint": {
          "builder": "@angular-eslint/builder:lint",
          "options": {
            "lintFilePatterns": [
              "src/**/*.{ts,html}"
            ]
          }
        }

This configuration ensures that the linting process is performed correctly for TypeScript and HTML files within the specified directory patterns. Adjust the lintFilePatterns array as needed to match the directory structure of your project(excluding those specified in the ignorePatterns setting).

If your project has multiple roots, as defined in the tsconfig file, you need to list them all in the lintFilePatterns array. Ensure that the patterns cover all the files intended for linting across these multiple roots.

        "lint": {
          "builder": "@angular-eslint/builder:lint",
          "options": {
            "lintFilePatterns": [
              "src/**/*.{ts,html}",
              "common/**/*.{ts,html}",
              "choice/**/*.{ts,html}",
              "errors/**/*.{ts,html}",
              [...]
              "text/**/*.{ts,html}"
            ]
          }
        }

corresponding to the following tsconfig section:

	"files": [
		"src/index.ts",
		"common/index.ts",
		"choice/index.ts",
		"errors/index.ts",
		[...]
		"text/index.ts",
	],

If you have Jest tests, you can utilize the provided eslint-plugin-jest plugin. No rules have been included here, as the plugin may raise complaints if the project does not utilize Jest You need to manually add recommended rules and corresponding overrides. Refer to the sample .eslintrc.js file for guidance

We suggest utilizing the Microsoft ESLint extension for Visual Studio Code (identified as dbaeumer.vscode-eslint). You can insert the following lines into your settings.json file (accessible through Ctrl+Shift+P > Preferences: Open Settings (JSON)):

  "eslint.options": {
    "extensions": [".js", ".ts", ".html"]
  },
  "eslint.alwaysShowStatus": true,

.gitignore

A foundational file to be duplicated into the root directory of your project, and tailored as necessary.

.husky

A directory to be copied to the root of your project, facilitating Husky.\ integration. It contains scripts that trigger commitlint and lint-staged.

You need to include the following lines in your package.json:

  "scripts": {
	  [...]
    "prepare": "husky install"
  },
  "lint-staged": {
    "*.scss": [
      "stylelint"
    ],
    "*.ts": [
      "eslint --no-ignore --max-warnings 0"
    ],
    "*.html": [
      "eslint --max-warnings 0"
    ]
  },

The max-warnings option halts the commit process if ESLint warnings are issued, not just for errors. Alerts such as incorrect indentation or missing semicolons are flagged as warnings to avoid excessive noise, but they still halt the commit and require resolution.

Note: If you exclude files in ESLint's ignorePatterns configuration and make changes to them (typically at the top-level of the project), ESLint will issue a warning, thus halting the commit.

In such cases, after addressing other issues, temporarily remove the ESLint-related settings (without committing package.json!), to circumvent the problem, and then restore them immediately after."

.stylelintrc

Configuration file for Stylelint. To incorporate it into your project, install ng-config-files as an npm dependency, then simply place the .stylelintrc file as it is in your project directory.

We suggest utilizing the official Stylelint extension for Visual Studio Code (identified as stylelint.vscode-stylelint). You can insert the following lines into your settings.json file (accessible via Ctrl+Shift+P > Preferences: Open Settings (JSON)):

  "css.validate": false,
  "scss.validate": false,
  "stylelint.validate": ["css", "scss"],

tsconfig.json

Configuration file for TypeScript and Angular compilation.

To incorporate it into your project, install ng-config-files as an npm dependency, and then reference this file from your main tsconfig.*.json file:

{
	"extends": "./node_modules/ng-config-files/configs/tsconfig.json",
	"compilerOptions": {
		// Options specific to your project
	},
	"angularCompilerOptions": {
		// Options specific to your project, maybe relaxing strict checks
	}
}

.eslintrc

This is a deprecated configuration file for ESLint, pointing to the eslint-old folder

tslint.json

This is a deprecated configuration file for TSLint.

Instead, use .eslintrc.js.

Development

This project necessitates Node.js 20.x+.

# clone the repository
git clone git@github.com:ahmedbhl/ng-config-files.git

# install dependencies
cd ng-config-files
npm ci

Unlike other frontend libraries, this project does not have a CI process and is not automatically published upon a new version. To release a new version:

Commit and push your changes to Github.
Version it using npm version [major|minor|patch] as usual. The tag is also pushed.
Publish the version using npm publish.