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

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: Result, the Result from running the formatter with execa

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

Development

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

Contributors

Josh Goldberg ✨ 💻 🖋 🤔 🚇 🚧 📆 🔧 📖

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