deno_fmt

The deno_fmt module provides a high-level API for formatting and checking source code, running on the deno fmt shell command and dprint WASM API. Both implementations are supported and can be used interchangeably depending on the environment the formatter is running in.

Usage

Deno CLI

For those using the Deno CLI or other environments with access to the Deno.Command API, the deno fmt shell command is the default formatter.

import { Formatter } from "https://deno.land/x/deno_fmt/mod.ts";

const fmt = await Formatter.initLegacy();

await fmt.format("const foo = {bar: 'baz'}");
// => const foo = { bar: "baz" };\n

fmt.formatSync("const foo = {bar: 'baz'}", { check: true });
// => false

WASM

For those using Deno Deploy or other environments without access to the Deno.Command API and the allow-run permission flag, the dprint WASM API is the default formatter.

import { Formatter } from "https://deno.land/x/deno_fmt/mod.ts";
const fmt = await Formatter.init();

await fmt.format("const a={b:'c'}"); // => const a = { b: "c" };\n
fmt.checkSync("const foo = {bar: 'baz'}"); // => false

API

Formatter

The Formatter class is the main entry point for the deno_fmt module. It provides a high-level API for formatting and checking source code, running on the deno fmt shell command and dprint WASM API. You can instantiate a new Formatter instance using the static method Formatter.init (WASM), or Formatter.initLegacy (CLI). You can also use the synchronous initSync and initLegacySync methods if you absolutely must use a synchronous API.

Static Method: Formatter.init

Asynchronously initializes a new Formatter instance using the dprint WASM formatting context, and with the specified configuration options. If no options are provided, the default options will be used.

import { Formatter } from "https://deno.land/x/deno_fmt/mod.ts";

const fmt = await Formatter.init();

const fmtCustom = await Formatter.init({
  ext: "md", // targets markdown files by default
  lineWidth: 100, // sets the line width to 100 characters
});

Static Method: Formatter.initLegacy(options?: Options)

Asyncronously initializes a new Formatter instance using the CLI formatting context, and with the specified configuration options. If no options are provided, the default options will be used.

import { Formatter } from "https://deno.land/x/deno_fmt/mod.ts";

// initialize the Deno CLI context with the default options:
const fmt = await Formatter.initLegacy();

// initialize the Deno CLI context with custom options:
const fmtCustom = await Formatter.initLegacy({
  singleQuote: true, // uses single quotes instead of double quotes
  useTabs: true, // uses tabs instead of spaces
});

Static Method: Formatter.initSync(options?: Options)

Synchronously initializes a new Formatter instance using the dprint WASM formatting context, and with the specified configuration options. If no options are provided, the default options will be used. This method is not recommended for use unless you absolutely must use a synchronous API. Instead, it's recommended that you instantiate the formatter asynchronously at the top level of your program, since ES modules are asynchronous by their very nature, and top-level await is supported in Deno.

import { Formatter } from "https://deno.land/x/deno_fmt/mod.ts";

// initialize the WASM context with default options:
const fmt = Formatter.initSync();

// initialize the WASM context with custom options:
const fmtCustom = Formatter.initSync({
  ext: "jsonc", // targets jsonc files by default
  lineWidth: 120, // sets the line width to 120 characters
});

Static Method: Formatter.initLegacySync(options?: Options)

Synchronously initializes a new Formatter instance using the CLI formatting context, with the specified configuration options. If no options are given, the default options will be used. This method is not recommended for use unless you absolutely must use a synchronous API. Instead, you should instantiate the formatter asynchronously at the top level of your program, since ES modules are asynchronous by their very nature, and top-level await is supported in Deno.

import { Formatter } from "https://deno.land/x/deno_fmt/mod.ts";

// initialize with the Deno CLI context and default options:
const fmt = Formatter.initLegacySync();

// initialize with the Deno CLI context and custom options:
const fmtCustom = Formatter.initLegacySync({
  ext: "tsx", // targets jsx/tsx files by default
  useTabs: true, // uses tabs instead of spaces
});

Instance Method: format

Asynchronously formats the given code, returning a Promise that resolves to the formatted code, or rejects with an error if it could not be formatted. This is the programmatic equivalent to the deno fmt CLI command. You may also provide an optional second argument, overrides, which will be merged on top of the instance options prior to formatting.

import { Formatter } from "https://deno.land/x/deno_fmt/mod.ts";

const fmt = await Formatter.init(); // initialize the formatter (WASM)

await fmt.format(`const foo = {bar: "baz"}`);
// => const foo = { bar: "baz" };\n

await fmt.format(`const foo = {bar: "baz"}`, { singleQuote: true });
// => const foo = { bar: 'baz' };\n

Instance Method: formatSync

Synchronously formats the given code, returning the formatted code. You may also provide an optional second argument, overrides, which will be merged on top of the instance options prior to formatting.

import { Formatter } from "https://deno.land/x/deno_fmt/mod.ts";

const fmt = await Formatter.init(); // initialize the formatter (WASM)

fmt.formatSync(`const foo = {bar: "baz"}`);
// => const foo = { bar: "baz" };\n

fmt.formatSync(`const foo = {bar: "baz"}`, { semiColons: false });
// => const foo = { bar: "baz" }\n

Instance Method: check

Asynchronously checks if the given code is formatted, returning a Promise that resolves to a boolean representing the result of the check. You may also provide an optional second argument, overrides, which will be merged on top of the instance options prior to checking. This is the programmatic equivalent to deno fmt --check in the CLI.

import { Formatter } from "https://deno.land/x/deno_fmt/mod.ts";

const fmt = await Formatter.init(); // initialize the formatter (WASM)

await fmt.check(`const foo = {bar: "baz"}`);
// => false

await fmt.check(`const foo = { bar: "baz" };\n`);
// => true

Instance Method: checkSync

Synchronously checks if the given code is formatted, returning a boolean representing the result of the check. You may also provide an optional second argument, overrides, which will be merged on top of the instance options prior to checking. This is the programmatic equivalent to deno fmt --check.

import { Formatter } from "https://deno.land/x/deno_fmt/mod.ts";

const fmt = await Formatter.init(); // initialize the formatter (WASM)

fmt.checkSync(`const foo = {bar: "baz"}`);
// => false

fmt.checkSync(`const foo = { bar: "baz" };\n`);
// => true

fmt.checkSync(`const foo = { bar: "baz" }\n`, { semiColons: false });
// => true

Performance Considerations

There are performance trade-offs between the two available context types.

WASM

If you're using the WASM formatting engine, you may notice a slight delay on initial load, due to the time it takes to instantiate the WASM binary (quite a large file). Once the binary is loaded, however, the WASM implementation's an extremely fast formatter, often clocking in speeds that are nearly as fast as returning cached results from the LRU cache.

CLI

If you're using the CLI formatting engine, you might notice a much faster start up time, but a slightly slower formatting time. This is due to the overhead of spawning a subprocess, and the additional cost of piping data to and from the spawned subprocess. However, the CLI implementation is still a very fast formatter, and is often only a few milliseconds slower than the WASM implementation.

If you can afford the initial load time, the WASM implementation will likely prove to be your best bet. However, if you cannot afford the initial loading time, but can afford to spare a few milliseconds on each format, the CLI implementation might be a better choice for you.

Unfortunately, if you're running in an environment like Deno Deploy, or if the allow-run permission is unavailable in your scenario, the CLI option is not available to you -- you'll have to use the WASM implementation.

Caching

Both implementations use an LRU cache to store previously formatted code, in order to avoid reformatting the same code multiple times. This cache can be disabled or configured by providing a cache option to the constructor or static initializer method of your choice.

Examples