ci: moving from eslint to biome #1283

erunion · 2025-07-02T00:53:22Z

🧰 Changes

I've been staring down the barrel of upgrading our shared ESLint config to support ESLint 9 over in readmeio/standards#993 and... I honestly would rather live my life instead. I've been really interested in https://biomejs.dev/ as of late and after playing around with it for not even 10 minutes I am sold.

It's almost a fully drop-in replacement for ESLint
I was able to configure and retain our opinionated import grouping ruleset¹ without any trouble.
It found and fixed issues that ESLint didn't, and can't, detect!
It linted our codebase in half a second vs ESLint taking 4.

They're still working on supporting Markdown and YAML so we can't fully ditch Prettier too but as it is Biome has got the juice.

https://github.com/readmeio/standards/blob/bc29338858c55da37631addb36582ec5feac11b0/packages/eslint-config/index.js#L25-L36 ↩

erunion · 2025-07-02T00:54:14Z

__tests__/bin.test.ts

 import { exec } from 'node:child_process';

-import { describe, it, expect } from 'vitest';
+import { describe, expect, it } from 'vitest';


Import sorting like this is an out of the box thing.

erunion · 2025-07-02T00:55:16Z

__tests__/commands/changelogs/index.test.ts

  describe('existing changelogs', () => {
-    let simpleDoc;
-    let anotherDoc;
+    let simpleDoc: PageObject;


It flagged that these didn't have an explicit type. I don't know where to put page.types.js but I didn't want to copy-paste this PageObject interface in a handful of files.

erunion · 2025-07-02T00:56:56Z

__tests__/helpers/vitest.matchers.ts


 declare module 'vitest' {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  // biome-ignore lint/suspicious/noExplicitAny: This is the type for a custom matcher.


I love that it requires you give a reason why you're ignoring a rule.

erunion · 2025-07-02T00:57:34Z

__tests__/lib/createGHA.test.ts

        expect(yamlOutput).toMatchSnapshot();
        expect(fs.writeFileSync).toHaveBeenCalledWith(getGHAFileName(fileName), expect.any(String));
-        expect(console.info).toHaveBeenCalledTimes(1);
+        expect(consoleInfoSpy).toHaveBeenCalledTimes(1);


Moved this over to the spy because it was already available and used in other tests, and also Biome was complaining about console.info being used and we had suppressed that at the top of file with ESLint.

erunion · 2025-07-02T00:59:04Z

biome.jsonc

+      // test result artifacts
+      "!coverage/**",
+
+      // release build artifacts
+      "!dist/**",
+      "!dist-gha/**",


I thought with vcs.useIgnoreFile: true we could get rid of these and have it automatically exclude files in our .gitignore file but it didn't work.

this feels like a pretty rough oversight and doesn't inspire confidence tbh 😔 but glad the workaround is easy enough at least. mind adding a comment explaining this?

erunion · 2025-07-02T00:59:51Z

src/commands/docs/migrate.ts


    validationHookResults.successes.forEach(success => {
-      if (success.result && success.result.pages.length) {
+      if (success.result?.pages.length) {


It recommended, but thankfully didn't autofix, that we move this to optional chaining.

erunion · 2025-07-02T01:00:20Z

src/commands/openapi/inspect.ts

+      // biome-ignore lint/performance/noAccumulatingSpread: @todo can this be improved?
      .reduce((prev, next) => Object.assign(prev, next));


We might be able to work around this rule but it's probably fine?

erunion · 2025-07-02T01:03:31Z

src/commands/openapi/reduce.ts

-            .map((p: string) => Object.keys(parsedPreparedSpec.paths?.[p] || {}))
-            .flat()


Blown away that it detected and autofixed this to a .flatMap().

erunion · 2025-07-02T01:04:28Z

src/commands/openapi/resolve.ts

    function replaceRef(schemaName: string, propertyName: string, refSchemaName: string) {
      const schema = schemas[schemaName];
-      if ('properties' in schema) {
-        schema.properties![propertyName] = { $ref: `#/components/schemas/${refSchemaName}` };


Rewrote this off of the non-null assertion because that was being picked up by their default ruleset.

erunion · 2025-07-02T01:05:55Z

.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["biomejs.biome"]


So far this extension seems to work as well as the ESLint one.

erunion · 2025-07-02T01:06:59Z

src/lib/frontmatter.ts

@@ -1,8 +1,8 @@
-import type { Mappings } from './readmeAPIFetch.js';


Always bugged me that our ESLint import grouping config never grouped type imports like non-type imports. Really neat that Biome just does it all.

erunion · 2025-07-02T01:08:17Z

src/lib/hooks/prerun.ts

  if (options.Command?.flags?.key) {
    this.debug('current command has --key flag');
    if (isTest()) {
-      // eslint-disable-next-line no-param-reassign


Not having a no-param-reassign rule might be an issue but with TS we've grown to be pretty good at not writing code that gets flagged with it.

src/lib/pageCommandProperties.ts

erunion · 2025-07-02T01:09:35Z

src/lib/unzip.ts


      return { pathInput: newWorkingDir, zipped: true as const, unzippedDir: newWorkingDir };
-    } catch (e) {
+    } catch (_e) {


Biome flags when we don't use variables but since we can't do } catch () { it says to prefix an unused variable with an underscore.

erunion · 2025-07-02T01:10:40Z

src/types.ts

 import type { PageRequestSchema, PageResponseSchema } from './lib/types/index.js';

 export type {
-  APIKeyRepresentation,


I'm full :sickos: mode over here at these imports being autofixed to be properly alphabetized now.

kanadgupta · 2025-07-02T00:54:17Z

.github/dependabot.yml

      prefix: chore(deps)
      prefix-development: chore(deps-dev)
    ignore:
-      # Blocked on this until we can bump our shared ESLint config to support ESLint 9


kanadgupta · 2025-07-08T23:36:54Z

bin/write-gha-pjson.js

  // set the correct targets for GitHub Actions
  current.oclif.commands.target = newTarget;
  Object.values(current.oclif.hooks).forEach(hook => {
-    // eslint-disable-next-line no-param-reassign


it looks like this rule exists and is set to a warning by default: https://biomejs.dev/linter/rules/no-parameter-assign/

any idea why it's not being fired?

Looks like it's not a part of the recommended ruleset.

Looks like it's part of the project domain but enabling linter.domains.project: all doesn't seem to enable it. Not sure why but I've manually turned it on and addressed a couple issues.

biome.jsonc

src/lib/logger.ts

src/lib/pageCommandProperties.ts

kanadgupta · 2025-07-09T00:00:27Z

src/lib/syncPagePath.ts

very glad that this file that we've spent so long in over the last few months has like zero issues lol 😮‍💨

kanadgupta

i'm slightly bummed about some of the rules we're losing (the eslint ecosystem is very difficult to top in this regard) but i think the tradeoffs seem worth it — eslint has been giving us grief for ages and biome's speed + out-of-the-box capabilities (the fact that it plays much better with TS 🫰🏽) + simpler configuration are all very promising.

this is a very big workflow change and i think we should make sure the team is fully on board before we move forward with other repos (and let's also make sure the custom rules support is adequate for our needs) but i'm in favor of this! let's also think about a shared config file that we publish from our standards repo at some point soon.

thanks for kicking off this effort ❤️‍🔥

kanadgupta · 2025-07-10T00:29:11Z

bin/set-version-output.js


-import { getNodeVersion, getMajorPkgVersion } from '../dist/lib/getPkg.js';
+// biome-ignore lint/correctness/useImportExtensions: This file exists but Biome wants to use the `.d.ts` file instead.
+import { getMajorPkgVersion, getNodeVersion } from '../dist/lib/getPkg.js';


weird — you'd think biome would be smart enough to know this is a .js file 🧐

yea it might be that it prefers TS over JS and sees d.ts there. will see if i can open up an issue with them

kanadgupta · 2025-07-10T00:30:12Z

biome.jsonc

+    "enabled": true,
+    "domains": {
+      "project": "all",
+      "test": "all",


do we need this? it looks like they auto apply it if it detects vitest in our deps: https://biomejs.dev/linter/domains/#test-dependencies

ugh nvm i just played around locally and looks like we need this 😔

kanadgupta · 2025-07-11T00:54:30Z

src/lib/promptWrapper.ts

+    // biome-ignore lint/style/noParameterAssign: This is safe to rewrite our incoming questions for `prompts`.
    questions = questions.map(question => ({ onRender, ...question }));
  } else {
-    // eslint-disable-next-line no-param-reassign


i can't tell if this is biome being incomplete in its analysis or if it's actually a galaxy brain approach by not flagging this lol

kanadgupta · 2025-07-11T00:54:56Z

src/lib/readmeAPIFetch.ts

 */
 function sanitizeHeaders(headers: Headers) {
  const raw = Array.from(headers.entries()).reduce<Record<string, string>>((prev, current) => {
-    // eslint-disable-next-line no-param-reassign


i don't understand when it does and doesn't flag this rule 😮‍💨

kanadgupta · 2025-07-11T01:15:58Z

.vscode/settings.json

+  },
  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  // explicitly disable ESLint to avoid conflicts with Biome
+  "eslint.enable": false,


i added the changes in this file b/c i imagine there might be weird side effects when vscode is running eslint + biome simultaneously and i figured it's safer to be explicit here. we should probably do the same with prettier (i.e., explicitly disable the prettier extension and set the default formatter to biome) if/when we migrate off of that too.

kanadgupta · 2025-07-11T01:33:18Z

biome.jsonc

+      // test result artifacts
+      "!coverage/**",
+
+      // release build artifacts
+      "!dist/**",
+      "!dist-gha/**",


this feels like a pretty rough oversight and doesn't inspire confidence tbh 😔 but glad the workaround is easy enough at least. mind adding a comment explaining this?

kanadgupta · 2025-07-16T23:09:36Z

🎉 This PR is included in version 10.5.0-next.1 🎉

The release is available on:

Your semantic-release bot 📦🚀

kanadgupta · 2025-08-22T14:30:04Z

🎉 This PR is included in version 10.5.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

refactor: moving from eslint to biome

30d0bd4

erunion requested a review from kanadgupta as a code owner July 2, 2025 00:53

erunion commented Jul 2, 2025

View reviewed changes

chore: committing our recommended vscode extensions file

72ab40e

erunion commented Jul 2, 2025

View reviewed changes

src/lib/pageCommandProperties.ts Show resolved Hide resolved

erunion commented Jul 2, 2025

View reviewed changes

erunion requested a review from emilyskuo July 2, 2025 01:11

erunion changed the title ~~refactor: moving from eslint to biome~~ ci: moving from eslint to biome Jul 8, 2025

erunion added the enhancement New feature or request label Jul 8, 2025

Merge branch 'next' into feat/biomejs

be609b3

kanadgupta reviewed Jul 9, 2025

View reviewed changes

erunion added 3 commits July 8, 2025 17:14

fix: pr feedback

f951d39

Merge branch 'next' into feat/biomejs

39a0738

fix: pr feedback

88176b3

erunion requested a review from kanadgupta July 9, 2025 00:19

erunion and others added 2 commits July 9, 2025 12:11

fix: upgrading biome + enabling the project domain

1ec9d66

chore: also update vscode settings file a bit

1db0354

kanadgupta approved these changes Jul 11, 2025

View reviewed changes

kanadgupta and others added 2 commits July 11, 2025 07:01

Merge branch 'next' into feat/biomejs

7e6f526

fix: adding a comment that useIgnoreFile doesn't seem to work

7b6a0ad

erunion merged commit 96c907c into next Jul 11, 2025
9 checks passed

erunion deleted the feat/biomejs branch July 11, 2025 20:12

kanadgupta added released on @next needs-backport-to-v9 PRs that need to backported to the 9.x channel labels Jul 16, 2025

kanadgupta added the released label Aug 22, 2025

		// biome-ignore lint/performance/noAccumulatingSpread: @todo can this be improved?
		.reduce((prev, next) => Object.assign(prev, next));

		.map((p: string) => Object.keys(parsedPreparedSpec.paths?.[p] \|\| {}))
		.flat()

		@@ -1,8 +1,8 @@
		import type { Mappings } from './readmeAPIFetch.js';

ci: moving from eslint to biome #1283

ci: moving from eslint to biome #1283

Uh oh!

Conversation

erunion commented Jul 2, 2025

🧰 Changes

Footnotes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

erunion Jul 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kanadgupta left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kanadgupta commented Jul 16, 2025

Uh oh!

kanadgupta commented Aug 22, 2025

Uh oh!

Reviewers

Assignees

erunion Jul 2, 2025 •

edited

Loading