@kitschpatrol/prettier-config

Prettier configuration for @kitschpatrol/shared-config.

Overview

It's a shared Prettier config, plus a command-line tool ksc-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 @kitschpatrol/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 @kitschpatrol/shared-config, which also automatically invokes the command line functionality in this package via its ksc 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:

   pnpm --package=@kitschpatrol/repo-config dlx ksc-repo init

2. Add the package:

   pnpm add -D @kitschpatrol/prettier-config

3. Add the starter .prettierrc.js and .prettierignore files to your project root, and add any customizations you'd like:

   pnpm exec ksc-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:

{
  "scripts": {
    "lint": "ksc-prettier lint",
    "fix": "ksc-prettier fix"
  }
}

You might need to pass certain plugins in explicitly if you're calling prettier directly. The ksc-prettier fix and ksc-prettier lint scripts take care of this for you.

Configuration

To create a prettier.config.ts in your project root:

pnpm exec ksc-prettier init

(Note that this will delete the prettier property in your package.json!)

Or

To create a prettier property in package.json:

pnpm exec ksc-prettier init --location package

(Note that this will delete the prettier.config.ts file in your project root!)

CLI

Command: ksc-prettier

Kitschpatrol's Prettier shared configuration tools.

This section lists top-level commands for ksc-prettier.

Usage:

ksc-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: ksc-prettier init

Initialize by copying starter config files to your project root or to your package.json file.

Usage:

ksc-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: ksc-prettier lint

Check that files are formatted according to your Prettier configuration. Matches files below the current working directory by default.

Usage:

ksc-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: ksc-prettier fix

Format files according to your Prettier configuration. Matches files below the current working directory by default.

Usage:

ksc-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: ksc-prettier print-config

Print the effective Prettier configuration. Package-scoped.. Searches up to the root of a monorepo if necessary..

Usage:

ksc-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.

import { clearCache, fix, fixFile } from '@kitschpatrol/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.

Astro support

Note that this configuration uses the @kitschpatrol/prettier-plugin-astro fork of the official Prettier plugin for Astro project.

This fork includes some fixes not yet merged into the official project.

Ruby support

Ruby formatting Expects a global Ruby install >=2.7 with the following gems:

• bundler
• prettier_print
• syntax_tree
• syntax_tree-haml
• syntax_tree-rbs

Locally, I provide this via rbenv at ~/.rbenv/shims/ruby, but other install techniques should work.

Note: Do not add plugins: ['prettier-plugin-ruby'] to the per-file scope, it must be global.

SQL support

Earlier versions of @kitschpatrol/prettier-config bundled prettier-plugin-sql for SQL formatting, but this has been removed due to the remarkable size of its node-sql-parser parser dependency.

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 indicates otherwise. So we use tabs.

The reluctant exceptions are:

YAML

Spaces are required by the specification.

Markdown and MDX

Spaces are not technically required, but are specified in alignment with the Remark project's conclusions and to prevent fragility in YAML frontmatter. (TODO: Need 4 spaces instead of 2?)

Shared plugins

See discussion in this prettier issue. 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.

License

MIT © Eric Mika