@rainstormy/presets-biome 2.0.0-alpha.2 → 2.0.0

package/README.md

@@ -1,46 +1,49 @@
 # Opinionated Presets for Biome
 
 This package provides predefined, opinionated [Biome](https://biomejs.dev)
-configurations to be applied to
-the [`extends`](https://biomejs.dev/guides/configure-biome/#share-a-configuration-file)
-property in `biome.json`.
+configurations carefully crafted for
+modern [TypeScript](https://www.typescriptlang.org) projects with add-ons
+for [Next.js](https://nextjs.org), [React Router](https://reactrouter.com),
+[Storybook](https://storybook.js.org), and [Vitest](https://vitest.dev).
 
 ## Code style
-The preset configurations apply the default formatting and linting rules in
-Biome with a few twists:
+The preset configurations apply the default formatting and enable most linting
+rules in Biome with a few twists:
 
-- **Locate source code in the `src` directory** to enable file globbing tools to
-  discover source code easily and to give all projects a consistent structure.
+- **Locate source code in the `src` directory** to improve discoverability and
+  scalability by simplifying glob patterns and giving all projects a consistent
+  structure.
 - **Omit semicolons** and rely fully
   on [automatic semicolon insertion](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#automatic_semicolon_insertion)
-  to reduce visual noise in the code. Using semicolons does not disable the
-  behaviour of automatic semicolon insertion anyway.
+  to reduce cognitive complexity and visual noise in the code. Using semicolons
+  does not disable the behaviour of automatic semicolon insertion anyway. See
+  also [Hacking Semicolons](https://slides.com/evanyou/semicolons) by Evan You.
 - **Use the generic `Array<T>` type** instead of the shorthand `T[]` syntax to
   make arrays of union types cleaner and to remain consistent with other
   built-in types such as `Set<T>`, `Map<K, V>`, and `Promise<T>`.
-- **Use PascalCase for filenames** in general to make the filenames consistent
-  with type declaration names and component names and to reduce the cognitive
-  load of having to consider multiple file naming conventions.
-
-To adjust the linting rules to the appropriate context, please adhere to the
-following additional file naming conventions:
-
-- `*.config.(js|ts)` for configuration files in a Node.js- and ESM-based
-  toolchain.
-- `*.stories.(ts|tsx)` for CSF3-based stories
-  in [Storybook](https://storybook.js.org).
-- `*.decorators.(ts|tsx)`
-  for [decorators](https://storybook.js.org/docs/writing-stories/decorators)
-  in Storybook.
-- `*.tests.(ts|tsx)` for test suites in [Vitest](https://vitest.dev).
-- `*.mocks.(ts|tsx)` for [module mocks](https://vitest.dev/guide/mocking#modules)
-  in Vitest.
-- `*.fixtures.(ts|tsx)` for predefined test data and samples imported by test
-  suites and stories.
+- **Use the `type` alias syntax** instead of the `interface` syntax to improve
+  flexibility with union types, intersection types, and generic wrapper types
+  such as `Readonly<T>` and `Partial<T>`.
+- **Access JSX component props directly on the `props` object** (including React
+  components) instead of destructuring it to avoid duplicating the prop names in
+  type declarations.
+- **Use a top-down declaration order** to improve readability and reduce
+  cognitive complexity by sticking to a predictable declaration order. See also
+  the [Stepdown Rule](https://dzone.com/articles/the-stepdown-rule), originally
+  described in Clean Code by Robert C. Martin (a.k.a. Uncle Bob).
+- **Use `function` declarations** instead of `const` with arrow functions to
+  improve type safety and to enable top-down declaration orders, as function
+  declarations are hoisted.
+- **Import `devDependencies` only in non-production code** such as configuration
+  files and tests to prevent accidental bundling of development dependencies in
+  production artefacts.
+- **Use PascalCase for filenames** to reduce cognitive complexity by sticking to
+  a simple naming convention that is consistent with type names and component
+  names.
 
 > [!NOTE]  
-> Biome uses **tabs** for indentation to gain accessibility by making the
-> indentation width customisable per developer, to reduce the number of required
+> Biome uses **tabs** for indentation to improve developers' accessibility
+> through customisable indentation widths, to reduce the number of required
 > keystrokes, and to reduce the file sizes.
 
 ## Installation
@@ -59,57 +62,50 @@ yarn add --dev @biomejs/biome @rainstormy/presets-biome
 ```
 
 ## Usage
-Create a [`biome.json`](https://biomejs.dev/reference/configuration) file and
-extend `@rainstormy/presets-biome/base` to enable opinionated formatting and
-linting.
-
-In addition to this, you can extend some of the following configurations to
-refine the Biome settings for your project:
-
-| Configuration                            | Description                                                                      |
-|------------------------------------------|----------------------------------------------------------------------------------|
-| `@rainstormy/presets-biome/nextjs`       | Adds support for [Next.js](https://nextjs.org) apps using the app router.        |
-| `@rainstormy/presets-biome/react-router` | Adds support for [React Router](https://reactrouter.com) apps using file routes. |
-| `@rainstormy/presets-biome/storybook`    | Adds support for CSF3-based stories in [Storybook](https://storybook.js.org).    |
-| `@rainstormy/presets-biome/vitest`       | Adds support for unit test suites in [Vitest](https://vitest.dev).               |
-
-You can override the predefined settings by specifying the desired options like
-`files` and `overrides` as usual.
-
-For example:
+Create a [`biome.json`](https://biomejs.dev/reference/configuration) file (or a
+`biome.jsonc` file)
+and [extend](https://biomejs.dev/guides/configure-biome/#share-a-configuration-file)
+`@rainstormy/presets-biome/2.2` to enable the opinionated formatting and linting
+configuration in general. Specify other options like `files` and `overrides` as
+usual. For example:
 
 ```json
 {
-  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.2.0/schema.json",
   "extends": [
-    "@rainstormy/presets-biome/base",
-    "@rainstormy/presets-biome/nextjs",
-    "@rainstormy/presets-biome/storybook",
-    "@rainstormy/presets-biome/vitest"
+    "@rainstormy/presets-biome/2.2"
   ],
   "files": {
-    "ignore": ["public/", "terraform/"]
-  },
-  "javascript": {
-    "formatter": {
-      "semicolons": "always"
-    }
+    "includes": [
+      ".github/**",
+      ".vscode/**",
+      "src/**",
+      "*.{js,json,jsonc,ts}"
+    ]
   },
   "overrides": [
     {
-      "include": ["src/app/**/*.tsx"],
+      "includes": ["src/**/*.tsx"],
       "linter": {
         "rules": {
           "correctness": {
-            "useExhaustiveDependencies": {
+            "noRestrictedElements": {
+              "level": "warn",
+              "options": {
+                "elements": {
+                  "a": "Use <Hyperlink> instead of <a>"
+                }
+              }
+            }
+          },
+          "style": {
+            "noRestrictedImports": {
               "level": "warn",
               "options": {
-                "hooks": [
-                  {
-                    "name": "useWindowEvent",
-                    "stableResult": true
-                  }
-                ]
+                "paths": {
+                  "next/image": "Use <FancyImage> instead of <NextImage>",
+                  "next/script": "Use <FancyScript> instead of <NextScript>"
+                }
               }
             }
           }
@@ -120,7 +116,103 @@ For example:
 }
 ```
 
+> [!TIP]  
+> Explicitly specified options in `biome.json` take precedence over the presets
+> in `extends`.
+
+### [Next.js](https://nextjs.org)
+Add `@rainstormy/presets-biome/2.2/nextjs` to the `extends` array to support the
+app router and React components in Next.js apps:
+
+```json
+{
+  "extends": [
+    "@rainstormy/presets-biome/2.2",
+    "@rainstormy/presets-biome/2.2/nextjs"
+  ]
+}
+```
+
+The `app` directory and the `instrumentation.ts` and `middleware.ts` files must
+reside in the `src` directory. React components and other files in general must
+_not_ reside in the `app` directory to improve the scalability of the project.
+
+### [React Router](https://reactrouter.com)
+Add `@rainstormy/presets-biome/2.2/react-router` to the `extends` array to
+support file routes and React components in React Router apps:
+
+```json
+{
+  "extends": [
+    "@rainstormy/presets-biome/2.2",
+    "@rainstormy/presets-biome/2.2/react-router"
+  ]
+}
+```
+
+The `routes` directory and the `root.tsx` and `routes.ts` files must reside in
+the `src` directory.
+
+### [Storybook](https://storybook.js.org)
+Add `@rainstormy/presets-biome/2.2/storybook` to the `extends` array to support
+the following kinds of files in Storybook (naming convention in parentheses):
+
+- Stories based on
+  the [Component Story Format](https://storybook.js.org/docs/api/csf) (CSF 3)
+  (`*.stories.{ts,tsx}`)
+- [Decorators](https://storybook.js.org/docs/writing-stories/decorators)
+  (`*.decorators.{ts,tsx}`)
+
+```json
+{
+  "extends": [
+    "@rainstormy/presets-biome/2.2",
+    "@rainstormy/presets-biome/2.2/storybook"
+  ]
+}
+```
+
+Add `.storybook/**` to the `files.includes` array to cover Storybook
+configuration files:
+
+```json
+{
+  "files": {
+    "includes": [
+      ".github/**",
+      ".storybook/**",
+      ".vscode/**",
+      "src/**",
+      "*.{js,json,jsonc,ts}"
+    ]
+  }
+}
+```
+
+Stories must remain simple in terms of cognitive complexity, limiting the use of
+conditional logic.
+
+### [Vitest](https://vitest.dev)
+Add `@rainstormy/presets-biome/2.2/vitest` to the `extends` array to support the
+following kinds of files in Vitest (naming convention in parentheses):
+
+- Unit test suites (`*.tests.{ts,tsx}`)
+- Test fixtures such as test data, stubs, and utilities (`*.fixtures.{ts,tsx}`)
+- [Module mocks](https://vitest.dev/guide/mocking#modules) (`*.mocks.{ts,tsx}`)
+
+```json
+{
+  "extends": [
+    "@rainstormy/presets-biome/2.2",
+    "@rainstormy/presets-biome/2.2/vitest"
+  ]
+}
+```
+
+To reduce the likelihood of buggy tests, test files must remain simple in terms
+of cognitive complexity, limiting the use of conditional logic.
+
 ### Eject from the preset
 Copy the relevant parts of
-the [preset source files](https://github.com/rainstormy/presets-biome/tree/main/src)
+the [preset source files](https://github.com/rainstormy/presets-biome/tree/main/src/2.2)
 and insert them directly into the `biome.json` file. Make adjustments as needed.

package/package.json

@@ -1,14 +1,22 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@rainstormy/presets-biome",
-  "version": "2.0.0-alpha.2",
-  "description": "Predefined, opinionated Biome configurations suitable for any web project.",
+  "version": "2.0.0",
+  "description": "Predefined, opinionated Biome configurations carefully crafted for modern TypeScript projects with add-ons for Next.js, React Router, Storybook, and Vitest.",
   "keywords": [
     "biome",
+    "configs",
     "formatter",
     "formatting",
     "linter",
-    "linting"
+    "linting",
+    "next",
+    "nextjs",
+    "react",
+    "react-router",
+    "storybook",
+    "typescript",
+    "vitest"
   ],
   "bugs": "https://github.com/rainstormy/presets-biome/issues",
   "repository": {