@envsa/prettier-config

# @envsa/prettier-config   [![NPM Package @envsa/prettier-config](https://img.shields.io/npm/v/@envsa/prettier-config.svg)](https://npmjs.com/package/@envsa/prettier-config) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/license/mit/)   **Prettier configuration for @envsa/shared-config.**  ## Overview It's a shared [Prettier](https://prettier.io) config, plus a command-line tool `envsa-prettier` to perform Prettier-related project initialization, linting, and fixing.  > [!IMPORTANT] > > **You can use this package on its own, but it's recommended to use [`@envsa/shared-config`](https://www.npmjs.com/package/@envsa/shared-config) instead for a single-dependency and single-package approach to linting and fixing your project.** > > This package is included as a dependency in [`@envsa/shared-config`](https://www.npmjs.com/package/@envsa/shared-config), which also automatically invokes the command line functionality in this package via its `envsa` command  ## Setup To use just this Prettier config in isolation: 1. Install the basic repository configuration files in your project root. This is required for correct PNPM behavior: ```sh pnpm --package=@envsa/repo-config dlx envsa-repo init ``` 2. Add the package: ```sh pnpm add -D @envsa/prettier-config ``` 3. Add the starter `prettier.config.ts` and `.prettierignore` files to your project root, and add any customizations you'd like: ```sh pnpm exec envsa-prettier init ``` ## Usage The Prettier binary should be picked up automatically by VS Code plugins. You can call it directly, or use the script bundled with the config. Integrate with your `package.json` scripts as you see fit, for example: ```json { "scripts": { "lint": "envsa-prettier lint", "fix": "envsa-prettier fix" } } ``` You might need to pass certain plugins in explicitly if you're calling `prettier` directly. The `envsa-prettier fix` and `envsa-prettier lint` scripts take care of this for you. ### Configuration To create a `prettier.config.ts` in your project root: ```sh pnpm exec envsa-prettier init ``` (Note that this will delete the `prettier` property in your `package.json`!) _Or_ To create a `prettier` property in `package.json`: ```sh pnpm exec envsa-prettier init --location package ``` (Note that this will delete the `prettier.config.ts` file in your project root!) ### CLI  #### Command: `envsa-prettier` Envsa's Prettier shared configuration tools. This section lists top-level commands for `envsa-prettier`. Usage: ```txt envsa-prettier <command> ``` | Command | Argument | Description | | -------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `init` | | Initialize by copying starter config files to your project root or to your package.json file. | | `lint` | `[files..]` | Check that files are formatted according to your Prettier configuration. Matches files below the current working directory by default. | | `fix` | `[files..]` | Format files according to your Prettier configuration. Matches files below the current working directory by default. | | `print-config` | | Print the effective Prettier configuration. Package-scoped.. Searches up to the root of a monorepo if necessary.. | | Option | Description | Type | | ------------------- | ------------------- | --------- | | `--help` `-h` | Show help | `boolean` | | `--version` `-v` | Show version number | `boolean` | _See the sections below for more information on each subcommand._ #### Subcommand: `envsa-prettier init` Initialize by copying starter config files to your project root or to your package.json file. Usage: ```txt envsa-prettier init ``` | Option | Description | Type | Default | | ------------------- | --------------------------------- | -------------------- | -------- | | `--location` | Where to store the configuration. | `"file"` `"package"` | `"file"` | | `--help` `-h` | Show help | `boolean` | | | `--version` `-v` | Show version number | `boolean` | | #### Subcommand: `envsa-prettier lint` Check that files are formatted according to your Prettier configuration. Matches files below the current working directory by default. Usage: ```txt envsa-prettier lint [files..] ``` | Positional Argument | Description | Type | Default | | ------------------- | ------------------------------ | ------- | ------- | | `files` | Files or glob pattern to lint. | `array` | `"."` | | Option | Description | Type | | ------------------- | ------------------- | --------- | | `--help` `-h` | Show help | `boolean` | | `--version` `-v` | Show version number | `boolean` | #### Subcommand: `envsa-prettier fix` Format files according to your Prettier configuration. Matches files below the current working directory by default. Usage: ```txt envsa-prettier fix [files..] ``` | Positional Argument | Description | Type | Default | | ------------------- | ----------------------------- | ------- | ------- | | `files` | Files or glob pattern to fix. | `array` | `"."` | | Option | Description | Type | | ------------------- | ------------------- | --------- | | `--help` `-h` | Show help | `boolean` | | `--version` `-v` | Show version number | `boolean` | #### Subcommand: `envsa-prettier print-config` Print the effective Prettier configuration. Package-scoped.. Searches up to the root of a monorepo if necessary.. Usage: ```txt envsa-prettier print-config ``` | Option | Description | Type | | ------------------- | ------------------- | --------- | | `--help` `-h` | Show help | `boolean` | | `--version` `-v` | Show version number | `boolean` |  ### API The package also exports `fix`, `fixFile` functions for formatting code programmatically, pre-configured with the shared Prettier configuration. ```typescript import { clearCache, fix, fixFile } from '@envsa/prettier-config'; // Format a string (defaults to TypeScript parser) const formatted = await fix('const x=1'); // Format with a virtual filepath for parser inference and override matching const markdown = await fix('# Hello\nworld', 'file.md'); // Both filepath and config overrides const result = await fix('const x = 1', 'file.ts', { printWidth: 80 }); // Format a file in place with config overrides await fixFile('./src/index.ts', { printWidth: 80 }); // Clear cached Prettier module and resolved plugin paths clearCache(); ``` Config is resolved in priority order: shared defaults < local project config (via `prettier.resolveConfig`) < per-call overrides. The Prettier module and resolved plugin paths are cached internally for performance across multiple calls. Use `clearCache()` to force re-initialization. ## Tabs vs. spaces Tabs are unambiguously preferred wherever the file format specification does not mandate spaces. Note that despite widely-accepted FUD regarding JSON requiring spaces, the [specification](https://www.json.org/json-en.html) indicates otherwise. So we use tabs. The reluctant exceptions are: ### YAML Spaces are required by the [specification](https://yaml.org/spec/1.2.2/#61-indentation-spaces). ### Markdown and MDX Spaces are not technically required, but are specified in alignment with the [Remark project's conclusions](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-tabs#recommendation) and to prevent fragility in YAML frontmatter. _(TODO: Need 4 spaces instead of 2?)_ ## Shared plugins See discussion in [this prettier issue](https://github.com/prettier/prettier/issues/15667). We set the `plugins` array in the shared config, and make sure that the plugin dependencies are hoisted by PNPM as specified in the `pnpm-workspace.yaml` file. ## Credits [Eric Mika](https://github.com/kitschpatrol) is the author of the original [@kitschpatrol/shared-config](https://github.com/kitschpatrol/shared-config) project on which this is based.  ## License [MIT](license.txt) © [Liam Rella](https://github.com/rellafella)