@nejs/styler

An AST-safe JavaScript styler that applies a small, opinionated, configurable rule set — built for people who want their code formatted to a real style guide, not the One True Brace defaults that Prettier and JSLint locked in.

@nejs/styler parses your source with acorn, applies a focused set of transformations through magic-string, and never reflows code it doesn't recognize. Run it locally to read code in your preferred style, even if the upstream repo uses a different formatter — your upstream's formatter will move it back the next time anyone touches the file.

Installation

npm install -g @nejs/styler
# or, project-local:
npm install --save-dev @nejs/styler

Usage

nejs-styler format src/                # rewrite files in place
nejs-styler check  src/                # exit non-zero if any file would change
nejs-styler diff   src/foo.mjs | less  # print a diff; never write
nejs-styler explain braces             # show a rule's docs
nejs-styler list                       # list every registered rule

File arguments may be paths to .mjs, .js, or .cjs files, or directories (recursive). node_modules and dot-directories are skipped automatically.

Rules

| Rule | What it does | |---|---| | jsdoc | Strips the - separator between a @param name and its description. Collapses column-aligned padding. Inserts a blank gutter line before @returns / @throws / @example. | | semicolons | Removes trailing statement semicolons. Keeps class-field declarations (#x;), for headers, and inter-statement separators on the same line (a(); b();). | | braces | Drops curly braces around control-flow bodies whose body is a single statement — even when that statement spans many lines (e.g. a return whose argument is a multi-line object literal). catch and finally always keep their braces because JS requires it. | | oneline-if-split | Splits if (cond) statement (and same-line for / while) into two lines: head on its own line, body indented underneath. | | vertical-spacing | Inserts a blank line between sibling statements when one or both is a control-flow statement (if / for / while / try / switch). Existing blank lines are preserved. |

Run nejs-styler explain <rule> to see each rule's full description.

What it doesn't touch

• Generic indentation, line wrapping, quote normalization, trailing commas — that's prettier's domain, and it does it well.
• Files it can't parse — a parse failure is reported as an error and the file is returned unchanged.

Example

Before:

/**
 * @param {string} name - The user's name.
 * @returns {string}
 */
function greet(name) {
  if (!name) {
    return 'hello, friend';
  }
  if (name === 'Brielle') {
    return 'hey there, captain';
  }
  return `hello, ${name}`;
}

After nejs-styler format:

/**
 * @param {string} name The user's name.
 *
 * @returns {string}
 */
function greet(name) {
  if (!name)
    return 'hello, friend'

  if (name === 'Brielle')
    return 'hey there, captain'

  return `hello, ${name}`
}

Configuration

Drop a .nejs-styler.json at your project root to tweak behavior:

{
  "indent": 2,
  "lineWidth": 80,
  "rules": {
    "vertical-spacing": "off"
  }
}

Per-rule values:

• "off" — disable the rule entirely
• object — pass rule-specific options (each rule documents what it accepts)

If no config file exists, the defaults match the rule table above.

Programmatic API

import { format, check, diff } from '@nejs/styler'

const result = format(sourceCode)
// { output, changed, results: [{ rule, edits, skipped, error? }] }

const status = check(sourceCode)
// { ok, results }

const dr = diff(sourceCode)
// { diff, changed, results }

Why?

I have a code style I like, that I write by hand, that doesn't match any of the popular formatter defaults. Prettier and JSLint both went the "no configuration, accept our defaults" route on purpose — fine for teams that don't care, painful when you do.

@nejs/styler is small enough (one parser, one transform helper, a handful of rule files) that I can read every line of it, extend it, and trust it on my own code. It runs against any JS file but doesn't try to be Prettier — it does the few things Prettier won't, and nothing else. Run it locally; let your upstream's formatter undo it.

License

MIT