Four Kitchens projects are expected to follow a consistent linting and formatting configuration so that developers can focus on solving problems, rather than making sure their code is formatted according to the preferences of one or more developer. This is accomplished through a variety of tools:
- Prettier for general code formatting across many file types.
- Commitlint to ensure semantic versioning and changelogs can be fully and accurately updated automatically.
- Stylelint to ensure error-free and consistently formatted style sheets (scss).
- ESLint to ensure error-free and consistently formatted JavaScript.
Prerequisites
Each environment that needs to pull @fourkitchens packages from GitHub needs to be authenticated using a "Personal Access Token". This only needs to be done once per-environment.
- Go to
https://github.com/settings/tokens/new
- In the "Note" field add something like "Four Kitchens GitHub Packages"
- Choose an expiration value
- Check the box for "write:packages" (this will automatically check all of the "repo" boxes as well)
- Click "Generate token"
- On your local machine, create an environment variable. *See the link below for details
- The
key
for Four Kitchens projects needs to beFOUR_KITCHENS_BUILD_TOKEN
- The
value
is the token you created above
- The
- Done!
*Here's a stack overflow post showing how to set persistent environment variables for various shells
There must be a .npmrc
file in the project root that tells npm to get @fourkitchens
packages from GitHub rather than npm.
- Create a
.npmrc
file in your project root (or modify an existing one) and add the following:
@fourkitchens:registry=https://npm.pkg.github.com
Then you can install the package like any other npm dependency.
npm install --save-dev @fourkitchens/eslint-config-and-other-formatting
All projects must utilize Prettier.
Opinionated code formatter with support for many file types. You can configure your editor to use prettier so that code is formatted on save, for example.
Prettier Setup
- To implement Prettier, create the file
.prettierrc.js
in the project root and add the following:
module.exports = {
...require('@fourkitchens/eslint-config-and-other-formatting/prettier.config'),
};
- Then, add this script to the
package.json
:
{
"scripts": {
"prettier": "prettier components --ignore-unknown --list-different"
}
}
(Replace components
with the path to the top-level directory that contains the project's source code.)
All projects must utilize Commitlint.
Run via Husky. Verifies commit messages follow the Conventional Commits standard for many reasons. In particular, that it facilitates automated release notes, and semantic version bumping.
Commitlint Setup
- To use Commitlint, create the file
commitlint.config.js
in the project root and add the following:
module.exports = {
extends: [
'@fourkitchens/eslint-config-and-other-formatting/commitlint.config',
],
};
- Install husky in the repository
npx husky install
- Create the husky script by running this in the project root:
npx husky add .husky/commit-msg 'npm run husky:commit-msg'
- Then define the script in the
package.json
{
"scripts": {
"husky:commit-msg": "commitlint --edit $1"
}
}
Stylelint must be implemented on projects that define custom stylesheets.
Stylelint is a linter that helps avoid errors and enforce conventions in style sheets. You can configure your editor to use stylelint so that code is formatted on save, for example.
Stylelint Setup
- To use it, create the file
stylelint.config.js
in the project root and add the following:
module.exports = {
extends: [
'@fourkitchens/eslint-config-and-other-formatting/stylelint.config',
],
};
- Then, add this script to the
package.json
:
{
"scripts": {
"lint:styles": "stylelint 'components/**/*.scss'"
}
}
(Replace components
with the path to the top-level directory that contains the project's source code.)
Eslint must be implemented on projects that define custom javascript.
Eslint is a tool for identifying and reporting on patterns found in ECMAScript/JavaScript code, with the goal of making code more consistent and avoiding bugs.
Eslint Setup
- To use it, create the file
.eslintrc.js
in the project root and add the following:
module.exports = {
extends: ['@fourkitchens/eslint-config-and-other-formatting'],
};
- Then, add this script to the
package.json
:
{
"scripts": {
"lint:js": "eslint components"
}
}
(Replace components
with the path to the top-level directory that contains the project's source code.)
Lint-staged is highly recommended since it will only lint modified files, making the development workflow significantly faster than linting an entire codebase whether or not files have changed.
Run via Husky. Used to lint only staged (changed) files, as opposed to the whole code base (Note: The whole code base will be linted later, as a check for anything that was forced through, etc. This mostly improves the day-to-day developer experience.)
Lint-staged Setup
- Create the husky script by running this in the project root:
npx husky add .husky/pre-commit 'npm run husky:pre-commit'
- Then define the script in the
package.json
{
"scripts": {
"husky:pre-commit": "lint-staged"
}
}
- Finally, define which file types to lint in your
package.json
. Below is an example that runs stylelint on scss files, eslint on js files and prettier on js, scss, and php files. Each project's requirements will vary, and may or may not need all of these (or more) so adjust according to the project needs.
{
"lint-staged": {
"components/**/*.scss": ["npm run lint:styles -- --fix"],
"components/**/*.js": ["npm run lint:js -- --fix"],
"components/**/*.{js,scss,php}": ["npm run prettier -- --write"]
}
}
The rest of this file needs updating. The PHP stuff should probably be removed entirely and released on packagist, rather than being a part of this npm package.
- If you're not familiar with linters, or how they work, there's a step-by-step example in Usage.md that walks you through everything documented here. Try it out!
- PHP_CodeSniffer: A PHP linter that ensures your code remains clean and consistent.
- Files:
.phpcs.xml
In this repo, we're linting the demo-files folder. Update this file for an actual projects needs.
- Affects Files:
- Files:
- Composer: A Dependency Manager for PHP
- Files:
- nvm: Define the supported node version in a
.nvmrc
file, and then typenvm use
into the terminal to ensure a consistent developer experience across environments. (Theuse
command can be automated per environment as well)- Files
.nvmrc
package.json
(This is not used directly by nvm, but by npm, which nvm installs...)
- Files
- Husky: Performs linting/formatting automatically around git commands. e.g.
git commit
,git push
, etc.- Files:
- Affects File:
package.json
There is very little you need to do locally to use this set of tools. An nvm use && npm install
will handle most of it. You can, however configure your editor to use the config files defined in the project by following their recommendations. Stylelint and Prettier each have documentation for setting up editor integration.
NOTE: This section is not complete.
- semantic-release or standard-version for automated version bumping (based on commit messages.)
- Run fixes to ensure nothing was forced through