Dhaka, Bangladesh
Home
About
Case Studies
Case Studies

JavaScript Linting & Formatting Setup for a WordPress Gutenberg Plugin

Cover image for the case study "JavaScript Linting & Formatting Setup for a WordPress Gutenberg Plugin"

Quick answer

Six years of unenforced JS standards, fixed with ESLint and a formatter in one commit, as groundwork before the larger CSS refactor.
I set up JavaScript linting and code formatting tooling in PostX's WordPress Gutenberg plugin codebase. The goal was to reduce code inconsistency, catch errors earlier, and create safer conditions for the larger CSS architecture refactor that followed.

TL;DR

One focused commit, six years of code with no enforced standards, landed in May 2025 - before the CSS refactor it was groundwork for.
TL;DR summary
ProblemNo linting or formatting standards existed in the PostX codebase, creating inconsistent code that was harder to read and riskier to refactor
What I didAdded ESLint and a JS formatter as dependencies, configured them for WordPress Gutenberg standards
Why it matteredConsistent, lint-clean code is easier to move safely - this was groundwork for the CSS component refactor
TeamSolo, with guidance from Samin Yaser
Paired withCSS architecture refactoring case study →

The problem

A mock diff showing most changed lines as pure formatting noise against the rare actual logic change, plus the three consequences: inconsistent code, no automatic error catching, and diffs that mix noise with substance.
PostX is a WordPress plugin built on Gutenberg blocks. Its codebase had grown over six years without enforced JS formatting standards. That meant: inconsistent indentation across files, no automatic catch for common JS mistakes, and diffs that mixed logic changes with whitespace noise - making code review harder and refactoring riskier. This matters more than it sounds. When you're about to move a lot of code around - as I was planning with the CSS component extraction - you want the baseline to be clean. Refactoring into inconsistent code just moves the mess.

Why I did this first

Linting first left a clean, attributable baseline; linting after the refactor would have buried new violations among pre-existing ones with no way to tell which was which.
I was already planning the CSS refactor. But I noticed the JS side of the codebase had no linting in place, and I knew that adding it after a major refactor is harder - you end up with lint errors mixed into new code, and it's difficult to tell what's a real issue and what's just a formatting artifact. So I set up linting first. It took one focused commit. Then I moved on to the larger structural work.

What I built

@wordpress/eslint-plugin paired with a non-conflicting formatter, producing one command to check every JS file and a clean baseline before the CSS refactor began.
The setup followed the WordPress ecosystem's conventions: @wordpress/eslint-plugin for Gutenberg-aware linting rules, and a formatter configured to avoid conflicts with the ESLint rules (a common pain point when adding both to an existing project). The result: every JS file in the codebase could now be checked for consistency in one command. Formatting differences stopped showing up as noise in diffs. And the codebase was in a cleaner state before the CSS refactor began.

The paired initiative

One commit of linting in May 2025 against roughly sixty commits of CSS refactor completed in September - two case studies, one code-quality initiative.
This case study and the CSS architecture refactoring case study are two parts of one code-quality initiative that ran through mid-2025. The linting work came first, in May 2025. The CSS refactor followed, completed September 2025, across ~60 commits. I've written them as separate case studies because they target different angles, but they're better understood together as a single push to make PostX's frontend codebase easier to work in.

What I'd do differently

Enforced new rules going forward while leaving pre-existing violations in place; next time, fix every violation immediately after setup instead.
I'd run the linter across the full codebase immediately after setup and fix all existing violations before moving on - rather than leaving pre-existing lint issues in place and only enforcing rules on new code going forward. Starting clean is easier than cleaning up incrementally later.

FAQ

The four judgment calls behind this initiative: why lint at all, why before the CSS refactor, why match team conventions, and why leave existing violations in place.

Why did you add linting at all, when the code already worked?

Because the code working isn't the same as the code being safe to change. Inconsistent formatting meant every diff mixed real logic changes with whitespace noise, which made review slower and made the upcoming refactor riskier to read.

Why do this before the CSS refactor rather than after?

Adding a linter after a large refactor buries you in violations you can't attribute - you can't tell what the refactor introduced from what was already there. Doing it first meant the baseline was clean, so anything the refactor broke stood out immediately.

Why configure it around the team's existing conventions instead of a standard config?

A generic config would have flagged patterns the team had already decided were fine, and the first thing anyone does with a noisy linter is disable it. Matching the rules the team already enforced by hand in review meant the tooling reinforced existing habits rather than fighting them.

Why did you leave the pre-existing violations in place?

I chose to enforce the rules going forward rather than block the setup on a codebase-wide cleanup. It got the tooling in place quickly, but I'd make the opposite call next time - see what I'd do differently above.

Part of the PostX frontend refactoring case study series →
On this page
Quick answer
TL;DR
The problem
Why I did this first
What I built
The paired initiative
What I'd do differently
FAQ
Why did you add linting at all, when the code already worked?
Why do this before the CSS refactor rather than after?
Why configure it around the team's existing conventions instead of a standard config?
Why did you leave the pre-existing violations in place?
I chose to enforce the rules going forward rather than block the setup on a codebase-wide cleanup. It got the tooling in place quickly, but I'd make the opposite call next time - see what I'd do differently above.
Case study 2 of 5 in the PostX series · View series overview
PreviousCSS Architecture Refactoring in a WordPress Gutenberg Plugin
NextWhat a Self-Proposed Engineering Initiative Looks Like