Code Formatter: Prettier #13

svengreb · 2020-06-19T18:32:33Z

A code formatter is a essential part of a project setup to ensure a good and consistent code style without requiring relatively time-consuming manual corrections found by a code linter. With code being automatically formatted on actions like saving a file the developer can focus entirely on the code instead of spending time and energy on indenting code line by line.

That‘s where one special project comes in: Prettier, the opinionated code formatter with support for almost any language and integration with almost every popular editor. I‘ve been using it since the first version and I totally forgot about the fact that formatting is even a thing. That could also be because [Gophers][] are already used to gofmt anyway.

Prettier is a absolute must-have for every project setup and I‘m not aware of any other projects with such advanced parsers and language support. The only negative point is that it is written in JavaScript instead of Go so it always pulls in NodeJS as a development dependency. This is not a problem at all for web-based projects, but for Go or any other non-NodeJS project it inflates the setup unnecessarily.

Anyway, the fantastic developer experience and project benefits clearly outweigh the negative points. In addition many developers today already have Node installed locally since it‘s large ecosystem has already spread by far further than just the web but already powers many system, desktop and CLI applications.

Configuration

This is one of the main features of Prettier: It already provides the best and recommended style configurations of-out-the-box™.
The only option we will change is the print width. It is set to 80 by default which is not up-to-date for modern screens (might only be relevant when working in terminals only like e.g. with Vim). It‘ll be changed to 120 like defined in all of my style guides.
The prettier.config.js configuration file will be placed in the project root as well as the .prettierignore file to also define ignore pattern.

Package Script

To allow to format all sources a format:pretty package script will be added that‘ll also run in the main format script flow.
A new lint:pretty script will also allow to check if all supported files are formatted correctly. It will be included in the main lint script flow.

The text was updated successfully, but these errors were encountered:

A code formatter is a essential part of a project setup to ensure a good and consistent code style without requiring relatively time-consuming manual corrections found by a code linter. With code being automatically formatted on actions like saving a file the developer can focus entirely on the code instead of spending time and energy on indenting code line by line. That's where one special project comes in: Prettier [1], the opinionated code formatter with support for almost any language and integration with almost every popular editor. I've been using it since the first version and I totally forgot about the fact that formatting is even a thing. That could also be because Gophers [2] are already used to `gofmt` [3] anyway. Prettier is a absolute must-have for every project setup and I'm not aware of any other projects with such advanced parsers and language support. The only negative point is that it is written in JavaScript instead of Go [4] so it always pulls in NodeJS [5] as a development dependency. This is not a problem at all for web-based projects, but for Go or any other non-NodeJS project it inflates the setup unnecessarily. Anyway, the fantastic developer experience and project benefits clearly outweigh the negative points. In addition many developers today already have Node installed locally since it's large ecosystem has already spread by far further than just the web but already powers many system, desktop and CLI applications. >>> Configuration This is one of the main features of Prettier: It already provides the best and recommended style configurations of-out-the-box. The only option that has been changed is the print width [6]. It is set to `80` by default which is not up-to-date for modern screens (might only be relevant when working in terminals only like e.g. with Vim). It has been changed to `120` like defined in all of my style guides [7]. The `prettier.config.js` configuration file is placed in the project root as well as the `.prettierignore` file to also define ignore pattern. >>> Package Script To allow to format all sources a `format:pretty` package script has been added that also runs in the main `format` script flow. The new `lint:pretty` script also allows to check if all supported files are formatted correctly. It is included in the main `lint` script flow. [1]: https://prettier.io [2]: https://blog.golang.org/gopher [3]: https://golang.org/cmd/gofmt [4]: https://go.dev [5]: https://nodejs.org [6]: https://prettier.io/docs/en/options.html#print-width [7]: https://github.com/arcticicestudio?tab=repositories&q=styleguide GH-13

A code formatter is a essential part of a project setup to ensure a good and consistent code style without requiring relatively time-consuming manual corrections found by a code linter. With code being automatically formatted on actions like saving a file the developer can focus entirely on the code instead of spending time and energy on indenting code line by line. That's where one special project comes in: Prettier [1], the opinionated code formatter with support for almost any language and integration with almost every popular editor. I've been using it since the first version and I totally forgot about the fact that formatting is even a thing. That could also be because Gophers [2] are already used to `gofmt` [3] anyway. Prettier is a absolute must-have for every project setup and I'm not aware of any other projects with such advanced parsers and language support. The only negative point is that it is written in JavaScript instead of Go [4] so it always pulls in NodeJS [5] as a development dependency. This is not a problem at all for web-based projects, but for Go or any other non-NodeJS project it inflates the setup unnecessarily. Anyway, the fantastic developer experience and project benefits clearly outweigh the negative points. In addition many developers today already have Node installed locally since it's large ecosystem has already spread by far further than just the web but already powers many system, desktop and CLI applications. >>> Configuration This is one of the main features of Prettier: It already provides the best and recommended style configurations of-out-the-box. The only option that has been changed is the print width [6]. It is set to `80` by default which is not up-to-date for modern screens (might only be relevant when working in terminals only like e.g. with Vim). It has been changed to `120` like defined in all of my style guides [7]. The `prettier.config.js` configuration file is placed in the project root as well as the `.prettierignore` file to also define ignore pattern. >>> Package Script To allow to format all sources a `format:pretty` package script has been added that also runs in the main `format` script flow. The new `lint:pretty` script also allows to check if all supported files are formatted correctly. It is included in the main `lint` script flow. [1]: https://prettier.io [2]: https://blog.golang.org/gopher [3]: https://golang.org/cmd/gofmt [4]: https://go.dev [5]: https://nodejs.org [6]: https://prettier.io/docs/en/options.html#print-width [7]: https://github.com/arcticicestudio?tab=repositories&q=styleguide Closes GH-13

svengreb · 2020-06-19T18:48:11Z

Resolved in 196cdf2.

Ensuring that documentations and content written in Markdown [1] are of great quality should be a continuous goal of any project. Persisting information is a consistent and extensive way helps tp keep a project healthy, no matter whether for long-time or new users ad well as maintainers and contributors. Linting Markdown results in better rendering with different markdown parsers and makes sure less refactoring is needed afterwards. The best solution for this task would be a tool written in Go [2], but the undisputed best tool is still remark-lint [3] which is (unfortunately) written in JavaScript and used via NodeJS [4]. Of course there are fantastic projects written in Go like goldmark [5] that provides a great way to _parse_ content, but linting is (currently) not a feature. remark-lint on the other side is built on top of remark [6], the powerful Markdown processor powered by plugins (such as remark-lint itself) and part of the unifiedjs [7] collective. It comes with really large set of customizable rule [8] and ways to ensure Markdown will be consistent across any project. Another decision point for remark-lint was the fact that Prettier has been added in GH-13 to this template so Node is already a development dependency anyway. This also allows to add other awesome projects that are (unfortunately) written in JavaScript and for which there is no comparable alternative. >>> Configuration remark-lint can be used via remark-cli [npm-rcli] and a rule preset. This preset is remark-preset-lint-arcticicestudio [10], my custom preset that implements my Markdown Style Guide [11]. Since the custom preset is still in major version `0` the version range is `>=0.x.x <1.0.0` to avoid the "SemVer Major Zero Caveat". When defining package versions with the the carat `^` or tilde `~` range selector it won't affect packages with a major version of `0`. Yarn will resolve these packages to their exact version until the major version is greater or equal to `1`. To avoid this caveat the more detailed version range `>=0.x.x <1.0.0` is used to resolve all versions greater or equal to `0.x.x` but less than `1.0.0`. This will always use the latest `0.x.x` version and removes the need to increment the version manually on each new release. The `.remarkrc.js` configuration file is placed in the project root as well as the `.remarkignore` file to also define ignore pattern. >>> Package Script To allow to run the Markdown linting separately a `lint:md` package script has been added and included in the main `lint` script flow. [1]: https://en.wikipedia.org/wiki/Markdown [2]: https://go.dev [3]: https://github.com/remarkjs/remark-lint [4]: https://nodejs.org [5]: https://github.com/yuin/goldmard [6]: https://remark.js.org [7]: https://unifiedjs.com [8]: https://github.com/remarkjs/remark-lint/blob/master/doc/rules.md [9]: https://www.npmjs.com/package/remark-cli [10]: https://github.com/arcticicestudio/remark-preset-lint-arcticicestudio [11]: https://arcticicestudio.github.io/styleguide-markdown GH-15

Ensuring that documentations and content written in Markdown [1] are of great quality should be a continuous goal of any project. Persisting information is a consistent and extensive way helps tp keep a project healthy, no matter whether for long-time or new users ad well as maintainers and contributors. Linting Markdown results in better rendering with different markdown parsers and makes sure less refactoring is needed afterwards. The best solution for this task would be a tool written in Go [2], but the undisputed best tool is still remark-lint [3] which is (unfortunately) written in JavaScript and used via NodeJS [4]. Of course there are fantastic projects written in Go like goldmark [5] that provides a great way to _parse_ content, but linting is (currently) not a feature. remark-lint on the other side is built on top of remark [6], the powerful Markdown processor powered by plugins (such as remark-lint itself) and part of the unifiedjs [7] collective. It comes with really large set of customizable rule [8] and ways to ensure Markdown will be consistent across any project. Another decision point for remark-lint was the fact that Prettier has been added in GH-13 to this template so Node is already a development dependency anyway. This also allows to add other awesome projects that are (unfortunately) written in JavaScript and for which there is no comparable alternative. >>> Configuration remark-lint can be used via remark-cli [npm-rcli] and a rule preset. This preset is remark-preset-lint-arcticicestudio [10], my custom preset that implements my Markdown Style Guide [11]. Since the custom preset is still in major version `0` the version range is `>=0.x.x <1.0.0` to avoid the "SemVer Major Zero Caveat". When defining package versions with the the carat `^` or tilde `~` range selector it won't affect packages with a major version of `0`. Yarn will resolve these packages to their exact version until the major version is greater or equal to `1`. To avoid this caveat the more detailed version range `>=0.x.x <1.0.0` is used to resolve all versions greater or equal to `0.x.x` but less than `1.0.0`. This will always use the latest `0.x.x` version and removes the need to increment the version manually on each new release. The `.remarkrc.js` configuration file is placed in the project root as well as the `.remarkignore` file to also define ignore pattern. >>> Package Script To allow to run the Markdown linting separately a `lint:md` package script has been added and included in the main `lint` script flow. [1]: https://en.wikipedia.org/wiki/Markdown [2]: https://go.dev [3]: https://github.com/remarkjs/remark-lint [4]: https://nodejs.org [5]: https://github.com/yuin/goldmard [6]: https://remark.js.org [7]: https://unifiedjs.com [8]: https://github.com/remarkjs/remark-lint/blob/master/doc/rules.md [9]: https://www.npmjs.com/package/remark-cli [10]: https://github.com/arcticicestudio/remark-preset-lint-arcticicestudio [11]: https://arcticicestudio.github.io/styleguide-markdown Closes GH-15

Git Hooks [1] are a fantastic way to customize the development workflow of a project to simplify and automate specific tasks that are required when working on the code base. For example, this includes tasks like formatting, "linting" and running tests before pushing a commit to ensure it conforms to the code style and works as expected. Most Git Hooks are not that complex and fullfil a simple purpose while other solutions like Danger [2] can help to manage larger projects and projects that need to scale. This "base" repository template initially uses a Git Hook that automatically runs configured linters on all files that have been staged and that match the configured pattern (file extension, filename etc.). Like documented in GH-15, NodeJS [3] is already a development dependency anyway so the lint-staged [4] NPM package is used for this goal. I've used this package in almost any project and it's again the most stable, production-proven and advanced tool that is currently out there with no comparable alternatives in other languages. >>> Configuration The configuration file `lint-staged.config.js` is placed in the project root and includes the command that should be run for matching file extensions (globs). Initialliy it includes the following three entries with the same order as listed here: 1. `prettier --list-different` - Runs Prettier [5] (GH-13) against `*.{js,json,md,yml}` to ensure all files are formatted correctly. The `--list-different` prints files that are not conform with the Prettier configuration. 2. `remark --no-stdout` - Runs remark-lint [6] (GH-15) against `*.md` to ensure all Markdown files are compliant to the style guide. The `--no-stdout` flag suppresses the output of the parsed file content. [1]: https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks [2]: https://danger.systems [3]: https://nodejs.org [4]: https://github.com/okonet/lint-staged [5]: https://prettier.io [6]: https://github.com/remarkjs/remark-lint GH-17

Git Hooks [1] are a fantastic way to customize the development workflow of a project to simplify and automate specific tasks that are required when working on the code base. For example, this includes tasks like formatting, "linting" and running tests before pushing a commit to ensure it conforms to the code style and works as expected. Most Git Hooks are not that complex and fullfil a simple purpose while other solutions like Danger [2] can help to manage larger projects and projects that need to scale. This "base" repository template initially uses a Git Hook that automatically runs configured linters on all files that have been staged and that match the configured pattern (file extension, filename etc.). Like documented in GH-15, NodeJS [3] is already a development dependency anyway so the lint-staged [4] NPM package is used for this goal. I've used this package in almost any project and it's again the most stable, production-proven and advanced tool that is currently out there with no comparable alternatives in other languages. >>> Configuration The configuration file `lint-staged.config.js` is placed in the project root and includes the command that should be run for matching file extensions (globs). Initialliy it includes the following three entries with the same order as listed here: 1. `prettier --check` - Runs Prettier [5] (GH-13) to ensure all files are formatted correctly. The `--list-different` prints files that are not conform with the Prettier configuration. 2. `remark --no-stdout` - Runs remark-lint [6] (GH-15) against `*.md` to ensure all Markdown files are compliant to the style guide. The `--no-stdout` flag suppresses the output of the parsed file content. [1]: https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks [2]: https://danger.systems [3]: https://nodejs.org [4]: https://github.com/okonet/lint-staged [5]: https://prettier.io [6]: https://github.com/remarkjs/remark-lint Closes GH-17

In GH-17 lint-staged [1] was added, a Git Hook [2] run linters against staged files before each commit. To automatically run this and other hooks that might be added later on, the hook manager and runner husky [3] is used. Like the already added tools Prettier [4], remark-lint [5] and lint-staged [6] it is (unfortunately) also written in JavaScript again Since NodeJS [7] is therefore already a development dependency it doesn't really matter that husky is another NPM package too. Unlike these previous tools there are indeed alternatives written in Go [8] like lefthook [9] or quickhook [10], but it requires time to test and evaluate them before actually replacing husky. Also a long as there are no comparable alternatives to the already used tools listed above, this template would be more complex by requiring both Node and Go as development dependency. Therefore husky takes over the part as hook manager & runner since it is a stable, production-proven and advanced project that I already use in almost any other project setup. >>> Configuration The `.huskyrc.js` configuration file is placed in the project root and includes the command to run for any supported Git hook [11]. Initially it contains entries for the following hooks: - `pre-commit` - Runs lint-staged (GH-17) before each commit to ensure all staged files are compliant to all style guides. [1]: https://github.com/okonet/lint-staged [2]: https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks [3]: https://github.com/typicode/husky [4]: #13 [5]: #15 [6]: #17 [7]: https://nodejs.org [8]: https://go.dev [9]: https://github.com/Arkweid/lefthook [10]: https://github.com/dirk/quickhook [11]: https://github.com/typicode/husky/blob/master/DOCS.md#supported-hooks GH-19

In GH-17 lint-staged [1] was added, a Git Hook [2] run linters against staged files before each commit. To automatically run this and other hooks that might be added later on, the hook manager and runner husky [3] is used. Like the already added tools Prettier [4], remark-lint [5] and lint-staged [6] it is (unfortunately) also written in JavaScript again Since NodeJS [7] is therefore already a development dependency it doesn't really matter that husky is another NPM package too. Unlike these previous tools there are indeed alternatives written in Go [8] like lefthook [9] or quickhook [10], but it requires time to test and evaluate them before actually replacing husky. Also a long as there are no comparable alternatives to the already used tools listed above, this template would be more complex by requiring both Node and Go as development dependency. Therefore husky takes over the part as hook manager & runner since it is a stable, production-proven and advanced project that I already use in almost any other project setup. >>> Configuration The `.huskyrc.js` configuration file is placed in the project root and includes the command to run for any supported Git hook [11]. Initially it contains entries for the following hooks: - `pre-commit` - Runs lint-staged (GH-17) before each commit to ensure all staged files are compliant to all style guides. [1]: https://github.com/okonet/lint-staged [2]: https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks [3]: https://github.com/typicode/husky [4]: #13 [5]: #15 [6]: #17 [7]: https://nodejs.org [8]: https://go.dev [9]: https://github.com/Arkweid/lefthook [10]: https://github.com/dirk/quickhook [11]: https://github.com/typicode/husky/blob/master/DOCS.md#supported-hooks Resolves GH-19