ts-pretty

Configurable prettier plugin which harnesses the TypeScript Compiler API.

Opinionated

Opinions vary, but if you share these opinions, this might be the plugin for you.

• Uniformity matters, but readability trumps uniformity every time.
• Formatting should enhance the readability of a language, not reduce it to a one size fits all formula.
• Formatting should allow code to be quickly absorbed / scanned, rather than forcing a careful reading of each line.

Overview

ts-pretty effectively replaces the generic TypeScript / JavaScript formatters built in to prettier, with the same TypeScript aware library used by vscode (i.e. the TypeScript Compiler API).

The TypeScript Compiler API contains a ts.Printer service, which is a highly opinionated pretty printer with no real configurability. However, it is written by the TypeScript team, obviously has an innate understanding of the language, and produces easily absorb-able / scan-able code.
ts.LanguageService is also built into TypeScript, and provides a highly configurable whitespace formatter.
Please see FormatCodeSettings in the ts definition file for a complete list of supported white space formatting options.

ts-pretty feeds your code into ts.Printer, and then passes that output into ts.LanguageService to create the final output for prettier. This is about as close as we are going to get to vscode, outside of vscode :-).

By default, ts-pretty picks up existing prettier options such as useTabs, tabWidth, singleQuote, etc. These options (along with all ts.FormatCodeSettings options) can be overridden using a json5 configuration file (ts-format.json) whose schema is ts.FormatCodeSettings.

Installation

ts-pretty requires prettier and typescript (even for JavaScript projects). These are peerDependencies and will be installed if not present.
Node.js 14.17.0+ is also required.

Simply install prettier-plugin-ts-pretty, and prettier will automatically use it whenever prettier is run.

npm install prettier-plugin-ts-pretty --save-dev

or

npm i prettier-plugin-ts-pretty -D

Caveat

This plugin overrides any previously loaded Prettier parsers for babel, babel-ts, espree, meriyah, acorn, and typescript (including the built-ins).
However, ts-pretty allows you to optionally use the output of the previously loaded parser as input to ts-pretty.
Additionally, ts-pretty allows you to optionally skip its own transformations.
The combination of these two options allow you to effectively disable ts-pretty, although why would you want to :astonished: ?

Options

| Name | Type | Default | Description | |------------------|-------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:----------------------------------------------| |tspTsConfig |string | process.env.TS_NODE_PROJECT ??'./tsconfig.json' ??hardcoded subset of tsconfig options | Path to a tsconfig.json file. | |tspTsFormat |string | hardcoded subset of ts.FormatCodeSettings | Path to a ts-format.json file. | |tspOrganizeImports|boolean| false | Removes unused, sorts by paths and names. | |tspDisable |boolean| false | Do not perform any ts-pretty transformations. | |tspUseBuiltins |boolean| false | Use a (appropriate) previously loaded parser. |

Usage

prettier --use-tabs --tsp-organize-imports --write .

Acknowledgments

Thanks to the TypeScript team, not only for the language, but also for implementing and exposing these capabilities.
Thanks to David Sherret for his countless contributions (all over the Internet) explaining how the TypeScript Compiler API actually works. And for ts-morph which is an amazing TypeScript utility.
Thanks to Simon Hänisch whose prettier-plugin-organize-imports project helped me understand how to override and integrate prettier builtins.

MIT License

Copyright (c) 2023 Frank Stock

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.