Formatly

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

Usage

formatly can automatically detect and format with:

• Biome
• deno fmt
• dprint
• Oxfmt
• 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:

1. Detect which supported formatter is configured in the repository
2. 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:

1. patterns: string[] (required): any number of glob patterns
2. 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"
   • order: FormatterName[] (optional): formatters to detect first, in order, as used by resolveFormatter
   • stopDirectory: StopDirectory (optional): directory to stop searching parent directories for a config file at, as used by resolveFormatter

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:

1. cwd: string (optional): working directory, if not "."
2. options: ResolveFormatterOptions (optional):
   • order: FormatterName[] (optional): formatters to detect first, in order
   • stopDirectory: StopDirectory (optional): directory to stop searching parent directories for a config file at, either a string path or a (currentDirectory: string) => boolean function

By default, only the working directory is searched for a config file. Passing stopDirectory also searches each parent directory in turn, stopping once the directory matching stopDirectory has been searched. A string is matched as a directory path, while a function is called with each directory and may return true to indicate the last directory to search. Reaching the file system root without a match throws an error, as that indicates a stopDirectory that isn't a parent of the working directory.

For example, to search up to whichever parent directory contains a .git directory:

import { resolveFormatter } from "formatly";
import { existsSync } from "node:fs";
import * as path from "node:path";

const formatter = await resolveFormatter("path/to/project", {
	stopDirectory: (currentDirectory) =>
		existsSync(path.join(currentDirectory, ".git")),
});

console.log(formatter);

By default, formatters are detected in their documented order. Passing order tries the named formatters first, in the order given; any formatter not named is tried afterwards in the default order. Duplicate names, and names that aren't supported formatters, throw an error.

For example, to detect Biome before Prettier:

import { resolveFormatter } from "formatly";

const formatter = await resolveFormatter("path/to/project", {
	order: ["biome", "prettier"],
});

console.log(formatter);

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:

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

Config files are only searched for in the working directory unless a stopDirectory is provided. package.json is always searched for in the working directory and its parent directories.

Supported Formatters

Formatter	Config File	Package Key	Script
Biome	Configure Biome		biome
deno fmt	Deno Configuration > Formatting		deno
dprint	dprint setup		dprint
Oxfmt	Oxfmt Configuration		oxfmt
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 🤔 💻 🐛

Eli 🐛

Josh Goldberg ✨ 💻 🖋 🤔 🚇 🚧 📆 🔧 📖 🐛

Lars Kappert 🐛 💻

rubiesonthesky 🐛

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