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"

--dry-run

Pass --dry-run to report which formatter was detected and the command that would run, without formatting anything:

npx formatly --dry-run "src/**/*.ts"

Detected prettier. 🔍
Would run: prettier --write --ignore-unknown src/**/*.ts

--help and --version

Pass --help (-h) to print usage information, or --version (-v) to print formatly's version.

Node.js API

npm i formatly

The formatly package exports the functions used by the formatly CLI, as well as a format function for formatting text in memory and a formatFiles function for formatting or checking files on disk.

format

Formats a string of text as if it were a file at a given path, without writing to disk.

import { format } from "formatly";
import fs from "node:fs/promises";

const report = await format("console.log(123)", { filePath: "src/index.ts" });

if (report.ran && !report.error) {
	await fs.writeFile("src/index.ts", report.formatted);
}

Parameters:

1. text: string (required): the text to format
2. options: FormatOptions (required):
   • filePath: string (required): path the text should be treated as being at, relative to cwd; formatters use it to infer the parser and apply any per-path config overrides
   • cwd: string (optional): working directory, if not "."
   • formatter: FormatterName (optional): explicit formatter to use instead of detecting one, as in formatly
   • 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 FormatReport, which is one of:

• FormatlyReportError if a formatter could not be determined, which is an object containing:
  • message: string
  • ran: false
• FormatReportFailure if the formatter ran but failed, such as on a syntax error, which is an object containing:
  • error: Error: the failure, including any output the formatter printed to stderr
  • formatter: Formatter: as resolved by resolveFormatter
  • ran: true
• FormatReportResult if the formatter succeeded, which is an object containing:
  • formatted: string: the formatted text
  • formatter: Formatter: as resolved by resolveFormatter
  • ran: true

Text is formatted by piping it through the formatter's CLI, so the formatter must be installed in the project. Prettier is instead run in memory using the project's own installed prettier package when it can be resolved from cwd. Biome is instead run in memory when the project installs @biomejs/js-api along with a @biomejs/wasm-nodejs matching its @biomejs/biome version, unless its config uses extends, is a nested ("root": false) config, or enables vcs.useIgnoreFile. dprint is instead run through one long-lived dprint editor-service process per cwd, which doesn't keep the Node.js process alive while idle.

Note: deno fmt can only be told the file's extension, not its path, so per-path config overrides in deno.json don't apply to format. fmt.exclude is honored by asking Deno about the file on disk, so it only applies to files that already exist.

formatFiles

Formats, or checks the formatting of, any number of files on disk in a single formatter invocation.

import { formatFiles } from "formatly";

const report = await formatFiles(["src/a.ts", "src/b.ts"], { check: true });

if (report.ran && !report.error) {
	console.log("Unformatted files:", report.changed);
}

Parameters:

1. filePaths: string[] (required): paths of the files to format, relative to cwd
2. options: FormatFilesOptions (optional):
   • check: boolean (optional): whether to report which files aren't formatted instead of formatting them
   • cwd: string (optional): working directory, if not "."
   • formatter: FormatterName (optional): explicit formatter to use instead of detecting one, as in formatly
   • 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 FormatFilesReport, which is one of:

• FormatlyReportError if a formatter could not be determined, which is an object containing:
  • message: string
  • ran: false
• FormatFilesReportFailure if the formatter ran but failed, which is an object containing:
  • error: Error: the failure, including any output the formatter printed to stderr when checking
  • formatter: Formatter: as resolved by resolveFormatter
  • ran: true
• FormatFilesReportResult if the formatter succeeded, which is an object containing:
  • changed: string[]: absolute paths of the files that were changed, or with check, that would be changed
  • formatter: Formatter: as resolved by resolveFormatter
  • ran: true

Note: Deno fails when none of the given files can be formatted without check, such as when they're all excluded.

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 "."
   • dryRun: boolean (optional): whether to resolve the command that would run without running it
   • formatter: FormatterName (optional): explicit formatter to use instead of detecting one, supports "biome", "deno", "dprint", "oxfmt", 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, one of:
    • FormatlyReportChildProcessResult if the formatter was spawned as a child process:
      • code: number | null: exit code of the child process
      • signal: NodeJS.Signal | null: signal that terminated the child process
    • FormatlyReportDryRunResult if dryRun was passed:
      • args: string[]: arguments of the command that would have run
      • command: string: the command that would have run
    • FormatlyReportVirtualResult if the formatter was run in memory:
      • code: number: exit code the formatter would have exited with as a child process

Spawned formatters' error output is passed through to the process's stderr, while their other output is ignored.

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 ("code" in result && result.code) {
	console.error(`${formatter.name} exited with code ${result.code}.`);
} 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();

// {
//   checker: [Function],
//   formatText: [Function],
//   name: "prettier",
//   runner: [Function],
//   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
  • checker: FormatterChecker: the function used to list which files aren't formatted
  • formatText: FormatterTextRunner: the function used to format text in memory
  • runner: FormatterRunner: the function used to run the formatter on files
  • 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. A package.json script running the formatter's format command, such as deno fmt
3. A package.json script mentioning the formatter's name as a whole word, such as deno task build
4. 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

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, on disk or in memory

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

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