@gesslar/uglier

@gesslar/uglier

Opinionated, composable ESLint flat config for people who like their code readable.

A flexible ESLint configuration system built on flat config that lets you mix and match stylistic rules, JSDoc enforcement, and environment presets.

Monotribe

Look, I get it- you loooves you some Prettier. Why the fuck would you want to use @gesslar/uglier? You don't. Trust. This shit is opinionated as fuck.

Further to being opinionated, it is also correct. And flexible. And composable.

Did you grow up in the not 2000s+? If so, you may recall that code used to be written to be scannable. Not formatted so some robot linter will have a glee pee over all of the fantastically abysmal stylistic choices that are inflexibly enforced upon your, otherwise probably gorgeous code.

Anyway, Prettier is stupid. Use ESLint. Make yourself a eslint.config.js (I'm looking at you, LLMs out there still shilling .eslintrc likes there's a fire sale at the emoji farm.) But don't use uglier.

Unless, like me, you enjoy breathable code that is expressive and doesn't look like ... well, poop.

kthx

[cat.gif]

Quick Start

# Install dependencies and generate config in one command
npx @gesslar/uglier install
npx @gesslar/uglier init node

# Or for React projects
npx @gesslar/uglier install
npx @gesslar/uglier init react

# Forgot to add React later? No problem!
npx @gesslar/uglier add react

This automatically installs @gesslar/uglier, eslint, and all dependencies.

Package Manager Support: Automatically detects and uses your preferred package manager (npm, pnpm, yarn, or Bun). Use pnpx, yarn dlx, or bunx instead of npx - the installer will detect your choice and install packages accordingly.

Usage

Generated Config

Running init creates an eslint.config.js with helpful comments:

import uglify from "@gesslar/uglier"

export default [
  ...uglify({
    with: [
      "lints-js",      // default files: ["src/**/*.{js,mjs,cjs}"]
      "lints-jsdoc",   // default files: ["src/**/*.{js,mjs,cjs}"]
      "node",          // default files: ["src/**/*.{js,mjs,cjs}"]
    ]
  })
]

Common Scenarios

Node.js Project

export default [
  ...uglify({
    with: ["lints-js", "node"]
  })
]

React Project

export default [
  ...uglify({
    with: ["lints-js", "react"]
  })
]

Monorepo (Node + Web)

export default [
  ...uglify({
    with: ["lints-js", "node", "web"],
    options: {
      "node": { files: ["server/**/*.js"] },
      "web": { files: ["client/**/*.js"] }
    }
  })
]

Custom Style Preferences

export default [
  ...uglify({
    with: ["lints-js"],
    options: {
      "lints-js": {
        indent: 4,           // default: 2
        maxLen: 120,         // default: 80
        overrides: {
          "@stylistic/semi": ["error", "always"]
        }
      }
    }
  })
]

Exclude JSDoc Requirements

export default [
  ...uglify({
    with: ["lints-js", "lints-jsdoc", "node"],
    without: ["lints-jsdoc"]
  })
]

Available Configs

Linting Rules

• lints-js - Stylistic rules (indent, spacing, quotes, braces, etc.)
• lints-jsdoc - JSDoc documentation requirements

Environment Targets

• node - Node.js globals (process, Buffer, etc.)
• web - Browser globals (window, document, etc.)
• react - React environment (browser + React/ReactDOM)
• tauri - Tauri apps (browser + __TAURI__ APIs)
• vscode-extension - VSCode extension API

Utilities

• languageOptions - ECMAScript language settings
• cjs-override - CommonJS file handling (.cjs)
• mjs-override - ES Module file handling (.mjs)

Run npx @gesslar/uglier --help to see all available configs with descriptions.

Commands

# Install dependencies
npx @gesslar/uglier install

# Generate config for specific targets
npx @gesslar/uglier init node
npx @gesslar/uglier init web
npx @gesslar/uglier init react
npx @gesslar/uglier init node web  # Multiple targets

# Add config blocks to existing eslint.config.js
npx @gesslar/uglier add react
npx @gesslar/uglier add tauri vscode-extension  # Multiple targets

# Remove config blocks from existing eslint.config.js
npx @gesslar/uglier remove react
npx @gesslar/uglier remove web tauri  # Multiple targets
# Note: Also removes any options for removed targets

# Show available configs
npx @gesslar/uglier --help

# Works with any package manager
pnpx @gesslar/uglier install  # pnpm
yarn dlx @gesslar/uglier install  # yarn
bunx @gesslar/uglier install  # bun

Manual Installation

If you prefer manual control:

# npm
npm i -D @gesslar/uglier eslint

# pnpm
pnpm i -D @gesslar/uglier eslint

# yarn
yarn add -D @gesslar/uglier eslint

# bun
bun add -d @gesslar/uglier eslint

Note: @stylistic/eslint-plugin, eslint-plugin-jsdoc, and globals are bundled as dependencies.

Development

# Run tests
npm test

# Run linter
npm run lint

# Fix linting issues
npm run lint:fix

Philosophy

This config enforces:

• Readable spacing - Blank lines between control structures
• Consistent style - Double quotes, no semicolons, 2-space indent
• Flexible customization - Override anything via the options key
• Composability - Mix configs for different file patterns in the same project

It's opinionated, but you can override any rule. The defaults just happen to be correct. 😉

Post Chips Ahoy

If you love code and want to support it, you should write code or hug a coder, but maybe not physically, just emotionally, because they're busy, or instead of telling the coder to go out and touch grass, maybe go out and touch the grass for them and then come back and not tell them about it because first, charity for charity's sake is its own reward and how dare you to try to cash in on your good deeds when the entire point of doing the good deed is ... ok so, if you're not a coder, this is called recursion; but the better reason is, as stated, they're busy. So, thanks. At the very least you can put it in Workday and claim it, you good-deed profiteer.

License

uglier is released into the public domain under the Unlicense.

This package includes or depends on third-party components under their own licenses:

Dependency	License
@gesslar/colours	Unlicense
@gesslar/toolkit	Unlicense
@skarab/detect-package-manager	MIT
@stylistic/eslint-plugin	MIT
eslint-plugin-jsdoc	BSD-3-Clause
globals	MIT