Nitpik JavaScript Formatter

by Nicholas C. Zakas

If you find this useful, please consider supporting my work with a donation.

Description

A pluggable JavaScript source code formatter.

Status

Prototype - Seeking feedback and not ready for production use.

Automatic Formatting

By default, Nitpik JavaScript automatically makes the following changes:

1. Collapses whitespace. Use a single space anywhere there's more than one space or other whitespace characters.
2. Removes trailing whitespace. Remove whitespace that appears before a line break.
3. Normalizes comma spacing. Spaces before commas are removed and spaces after commas are added where expected (spaces are not added when the comma is immediately followed by a line break).
4. Normalizes semicolon spacing. Spaces before semicolons are removed and spaces after semicolons are added where expected (spaces are not added when the semicolon is immediately followed by a line break).

Usage

Node.js

Install using [npm][npm] or [yarn][yarn]:

npm install @nitpik/javascript --save

# or

yarn add @nitpik/javascript

Import into your Node.js project:

// CommonJS
const { JavaScriptFormatter } = require("@nitpik/javascript");

// ESM
import { JavaScriptFormatter } from "@nitpik/javascript";

Deno

Import into your Deno project:

import { JavaScriptFormatter } from "https://unpkg.com/@nitpik/javascript/dist/pkg.js";

Browser

Import into a browser script:

import { JavaScriptFormatter } from "https://unpkg.com/@nitpik/javascript/dist/pkg.js";

API

After importing, create a new instance of JavaScriptFormatter. The constructor accepts one argument which is a configuration object with the following keys:

• style - formatting options
  • collapseWhitespace - whether multiple spaces in a row should be collapsed into one (default: true)
  • emptyLastLine - should the input end with a line break (default: true)
  • indent - either the character to use for indents or the number of spaces (default: 4)
  • lineEndings - the line ending format, either "windows" or "unix" (defualt: "unix")
  • maxEmptyLines - the maximumn number of empty lines allowed before collapsing (default: 1)
  • maxLineLength - the maximum length of a line before wrapping (defualt: Infinity)
  • quotes - the style of quotes to use, either "single" or "double" (default: "double")
  • semicolons - whether or not to use semicolons (default: true)
  • tabWidth - the number of spaces to count for each tab character (defualt: 4)
  • trailingCommas - whether trailing commas should be used for multiline object and array literals (default: false)
  • trimTrailingWhitespace - should trailing whitespace be removed (default: true)
• plugins - Optional. An array of plugins (see below for examples).

For example:

const formatter = new JavaScriptFormatter({
    style: {
        indent: "\t",
        quotes: "single"
    }
});

const result = formatter.format(yourJavaScriptCode);

Plugins

A plugin is a function that accepts one parameter, context, and returns an object specifying the types of nodes to visit in a JavaScript abstract syntax tree (AST). Here's an example that ensures there's an empty line before each function declaration:

function emptyLineBeforeFunctions(context) {

    const { layout } = context;

    return {
        FunctionDeclaration(node) {
            layout.emptyLineBefore(node);
        }
    };
}

This function uses the context.layout property to specify that there should be an empty line before each function declaration node. FunctionDeclaration is the type of node to look for, as defined by ESTree. The node is passed as an argument to each method as the AST is traversed, so in this example, node represents a function declaration. You can then include the function in the plugins array of the configuration options:

const formatter = new JavaScriptFormatter({
    style: {
        indent: "\t",
        quotes: "single"
    },
    plugins: [
        emptyLineBeforeFunctions
    ]
});

const result = formatter.format(yourJavaScriptCode);

When the formatter is run, it will now run any specified plugins after a first-pass of formatting based on the style options. This makes it easy to define a default style and then modify it to suit your needs.

All of the style options are implemented internally as plugins. Please see the src/plugins directory for examples (documentation to come later).

Developer Setup

1. Ensure you have Node.js 12+ installed
2. Fork and clone this repository
3. Run npm install
4. Run npm test to run tests

License and Copyright

This code is licensed under the Apache 2.0 License (see LICENSE for details).

Copyright Human Who Codes LLC. All rights reserved.