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:
text: string(required): the text to format
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
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.
cwd: string(optional): working directory, if not "."
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.
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:
Existence of the formatter's default supported config file name
A package.json script running the formatter's format command, such as deno fmt
A package.json script mentioning the formatter's name as a whole word, such as deno task build
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.
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.