formatly

Formatly

Formats your code with whatever formatter your project is already using. 🧼

Usage

formatly can automatically detect and format with:

• Biome
• deno fmt
• dprint
• Prettier

See Formatter Detection for details on how they are detected.

CLI

npx formatly <files>

formatly takes in any number of glob patterns. It will then:

• Detect which supported formatter is configured in the repository
• Pass those glob patterns directly to the formatter

For example, to match all directories and folders in the current directory:

npx formatly *

To match only .ts files in src/:

npx formatly "src/**/*.ts"

Node.js API

npm i formatly

The formatly package exports the functions used by the formatly CLI.

formatly

Runs formatting on any number of glob pattern strings.

import { formatly } from "formatly";

await formatly(["*"]);

Parameters:

• patterns: string[] (required): any number of glob patterns
• options: FormatlyOptions (optional):
  • cwd: string (optional): working directory, if not "."
  • formatter: FormatterName (optional): explicit formatter to use instead of detecting one, supports "biome", "deno", "dprint", and "prettier"

Resolves with a FormatlyReport, which is either:

• FormatlyReportError if a formatter could not be determined, which an object containing:
  • ran: false
• FormatlyReportResult if a formatter could be determined, which is an object containing:
  • formatter: Formatter: as resolved by resolveFormatter
  • ran: true
  • result: FormatlyReportChildProcessResult:
    • code: number | null: exit code of the child process
    • signal: NodeJS.Signal | null: signal that terminated the child process

For example, to run formatting on TypeScript source files in a child directory and check the result:

import { formatly } from "formatly";

const report = await formatly(["src/**/*.ts"], { cwd: "path/to/project" });

if (!report.ran) {
	console.error("Could not determine formatter.");
	return;
}

const { formatter, result } = report;

if (result.code) {
	console.error(`Error running ${formatter.runner}:`, result.stderr);
} else {
	console.log(`Formatted with ${formatter.name}! 🧼`);
}

resolveFormatter

Detects which of the supported formatters to use for a directory.

import { resolveFormatter } from "formatly";

const formatter = await resolveFormatter();

// {
//   name: "Prettier",
//   runner: "npx prettier --write",
//   testers: { ... }
// }
console.log(formatter);

Parameters:

• cwd: string (optional): working directory, if not "."

Resolves with either:

• undefined if a formatter could not be detected
• Formatter if one can be found, which is an object containing:
  • name: string: English name of the formatter
  • runner: string: the shell command used to run the formatter
  • testers: object: strings and regular expressions used to test for the formatter

Formatter Detection

Formatters are detected based on the first match from, in order:

• Existence of the formatter's default supported config file name
• The formatter's name in a package.json fmt or format script
• Well-known root-level package.json key

Supported Formatters

Formatter	Config File	Package Key	Script
Biome	Configure Biome		biome
deno fmt	Deno Configuration > Formatting		deno
dprint	dprint setup		dprint
Prettier	Prettier Configuration File	"prettier"	prettier

Want support for a formatter not mentioned here? Great! Please file a feature request GitHub issue. 🙏

Why?

Formatly is a tool for any developer tool that creates files for users. If your tool creates, say, a config file that users are meant to check into their repository, you probably want that file to be formatted per the user's preference. But there are several popular formatters in use today: it's not enough to just call to prettier.format.

Formatly takes away the burden of

• Detecting which formatter -if any- a userland project is using
• Calling to that formatter's API(s) to format the file

Does Formatly replace Prettier, etc.?

No. Formatly is a detection + wrapping layer around formatters such as Prettier. Userland projects still need to configure a formatter themselves.

Development

See .github/CONTRIBUTING.md, then .github/DEVELOPMENT.md. Thanks! 🧼

Contributors

Alec Larson 🤔 💻

Bjorn Lu 🤔 💻 🐛

Josh Goldberg ✨ 💻 🖋 🤔 🚇 🚧 📆 🔧 📖

💝 This package was templated with create-typescript-app using the Bingo framework.