@airteam/oxc-config 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,124 @@
-# Temporary Holding Version
+# @airteam/oxc-config
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Airteam's shared [Oxlint](https://oxc.rs/docs/guide/usage/linter.html) and [Oxfmt](https://oxc.rs/docs/guide/usage/formatter.html) configs for TypeScript and JavaScript projects.
+
+## Set up a project
+
+Install the package and its peers. It requires Node.js 22.23 or later.
+
+```sh
+pnpm add -D @airteam/oxc-config oxlint oxfmt oxlint-tsgolint
+```
+
+Create `oxlint.config.ts` and `oxfmt.config.ts` in the project root:
+
+```ts
+import { createLintConfig } from "@airteam/oxc-config/oxlint";
+
+export default createLintConfig({ nextjs: true, vitest: true });
+```
+
+```ts
+import { createFormatConfig } from "@airteam/oxc-config/oxfmt";
+
+export default createFormatConfig();
+```
+
+Add the scripts:
+
+```json
+{
+  "scripts": {
+    "lint": "oxlint .",
+    "lint:fix": "oxlint --fix . && oxfmt . && oxlint .",
+    "format": "oxfmt .",
+    "format:check": "oxfmt --check ."
+  }
+}
+```
+
+Type-aware checking is on by default and needs a `tsconfig.json` that TypeScript 7 accepts. Pass `typeAware: false` if your project isn't ready for it.
+
+The React profiles use a plugin that declares an ESLint peer even though it runs under Oxlint. To skip installing ESLint with pnpm, add this to the project's `pnpm-workspace.yaml` before installing:
+
+```yaml
+autoInstallPeers: false
+peerDependencyRules:
+  ignoreMissing:
+    - eslint
+```
+
+To share the strict compiler settings, extend the base config from the project's `tsconfig.json`:
+
+```json
+{
+  "extends": "@airteam/oxc-config/tsconfig"
+}
+```
+
+## Choose options
+
+Enable only what the project uses. In a monorepo, scope each option to the files or directories that use it.
+
+| Option               | Value                                 | Adds                                                                                                                                                        |
+| -------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `node`               | `true` or globs                       | Node.js environment and rules                                                                                                                               |
+| `react`              | `true` or globs                       | React, React Compiler, accessibility and effect rules                                                                                                       |
+| `nextjs`             | `true` or application directories     | The React rules plus Next.js rules and its default-export entrypoints                                                                                       |
+| `reactNative`        | `true` or application directories     | The React rules, with default exports allowed for `App` and `app/`                                                                                          |
+| `vitest`, `jest`     | `true` or globs                       | The test runner's rules. The globs join the test files                                                                                                      |
+| `effect`             | `true` or globs                       | Effect error-tag and service-import rules                                                                                                                   |
+| `electron`           | `true` or `{ renderer: [...] }`       | Electron security rules everywhere, and an import boundary keeping `electron` and `node:*` out of the renderer (`src/renderer/**` by default). Needs `root` |
+| `tests`              | Globs                                 | Extra test files, such as Playwright tests                                                                                                                  |
+| `env`                | The modules that read the environment | `process.env` and `import.meta.env` reads only in those modules                                                                                             |
+| `clock`, `random`    | The modules that own each             | Current-time reads and random values only in those modules                                                                                                  |
+| `boundaries`         | Import boundaries                     | Imports that must not cross parts of the project. Needs `root`                                                                                              |
+| `serverActionGuards` | Guard function names                  | `"use server"` actions that must start by awaiting a guard                                                                                                  |
+
+```ts
+import { createLintConfig } from "@airteam/oxc-config/oxlint";
+
+export default createLintConfig({
+  root: import.meta.dirname,
+  nextjs: ["apps/web"],
+  reactNative: ["apps/mobile"],
+  node: ["services/**"],
+  vitest: true,
+  env: ["apps/web/src/env.ts"],
+});
+```
+
+The [configuration guide](https://github.com/jameswyse/oxc-config/blob/main/docs/configuration.md) describes each option in detail, and its [rule reference](https://github.com/jameswyse/oxc-config/blob/main/REFERENCE.md) lists what each rule rejects.
+
+## Add project exceptions
+
+Pass `rules`, `overrides` and `ignorePatterns` to the same call:
+
+```ts
+import { createLintConfig } from "@airteam/oxc-config/oxlint";
+
+export default createLintConfig({
+  nextjs: true,
+  ignorePatterns: ["src/generated/**"],
+  rules: { "wyse/no-swallowed-errors": "off" },
+  overrides: [{ files: ["src/validation/**"], rules: { "wyse/no-runtime-typeof": "off" } }],
+});
+```
+
+- `rules` changes a rule wherever the shared config enables it, so a test rule stays scoped to test files. A severity on its own keeps the rule's options.
+- `overrides` are added after the shared overrides, so they win.
+- `ignorePatterns` are added to the shared ignore patterns.
+
+`createFormatConfig` takes Oxfmt options the same way, such as `createFormatConfig({ singleQuote: true })`.
+
+If several projects need the same exception, change the shared rules instead.
+
+## Change the shared rules
+
+The team owns this package. Open a pull request here to change what every project lints.
+
+- [`src/oxlint/config.ts`](src/oxlint/config.ts) is the whole policy. `base` lists the rule profiles every project gets, `profiles` lists the options a project can switch on, and `rules` changes single rules.
+- [`src/oxlint/profiles`](src/oxlint/profiles) holds Airteam's own profiles, such as `reactNative`.
+- [`src/oxfmt/config.ts`](src/oxfmt/config.ts) holds the formatter defaults.
+
+[Build a preset](https://github.com/jameswyse/oxc-config/blob/main/docs/presets.md) explains profiles, layers and how to write or extend one.

package/dist/oxfmt/config.d.ts

@@ -0,0 +1 @@
+export declare const createFormatConfig: (options?: import("oxfmt").OxfmtConfig) => import("@jameswyse/oxc-config/oxfmt/preset").FormatConfig;

package/dist/oxfmt/config.js

@@ -0,0 +1,3 @@
+import { createFormatConfig as createSharedFormatConfig } from "@jameswyse/oxc-config/oxfmt";
+import { defineFormatPreset } from "@jameswyse/oxc-config/oxfmt/preset";
+export const createFormatConfig = defineFormatPreset(createSharedFormatConfig());

package/dist/oxlint/config.d.ts

@@ -0,0 +1,18 @@
+export declare const createLintConfig: (options?: import("@jameswyse/oxc-config/oxlint/preset").LintOptions<{
+    node: import("@jameswyse/oxc-config/oxlint/preset").FileScope;
+    react: import("@jameswyse/oxc-config/oxlint/preset").FileScope;
+    nextjs: import("@jameswyse/oxc-config/oxlint/preset").AppRoots;
+    reactNative: import("@jameswyse/oxc-config/oxlint/preset").AppRoots;
+    vitest: import("@jameswyse/oxc-config/oxlint/preset").FileScope;
+    jest: import("@jameswyse/oxc-config/oxlint/preset").FileScope;
+    effect: import("@jameswyse/oxc-config/oxlint/preset").FileScope;
+    electron: true | {
+        renderer?: string[];
+    };
+    env: import("@jameswyse/oxc-config/oxlint/preset").OneOrMore<string>;
+    clock: import("@jameswyse/oxc-config/oxlint/preset").OneOrMore<string>;
+    random: import("@jameswyse/oxc-config/oxlint/preset").OneOrMore<string>;
+    boundaries: import("@jameswyse/oxc-config/oxlint/preset").ImportBoundary[];
+    serverActionGuards: import("@jameswyse/oxc-config/oxlint/preset").OneOrMore<string>;
+}> | undefined) => import("@jameswyse/oxc-config/oxlint/preset").SharedLintConfig;
+export type LintOptions = NonNullable<Parameters<typeof createLintConfig>[0]>;

package/dist/oxlint/config.js

@@ -0,0 +1,22 @@
+import { defineLintPreset } from "@jameswyse/oxc-config/oxlint/preset";
+import { boundaries, clock, comments, core, effect, electron, env, errors, jest, modules, mutation, nextjs, node, random, react, security, serverActionGuards, spacing, tests, types, vitest, } from "@jameswyse/oxc-config/oxlint/profiles";
+import { reactNative } from "./profiles/react-native.js";
+export const createLintConfig = defineLintPreset({
+    base: [core, types, security, errors, modules, comments, mutation, tests, spacing],
+    profiles: {
+        node,
+        react,
+        nextjs,
+        reactNative,
+        vitest,
+        jest,
+        effect,
+        electron,
+        env,
+        clock,
+        random,
+        boundaries,
+        serverActionGuards,
+    },
+    rules: { "wyse/no-comments": "off" },
+});

package/dist/oxlint/profiles/react-native.d.ts

@@ -0,0 +1,2 @@
+import type { AppRoots, Profile } from "@jameswyse/oxc-config/oxlint/preset";
+export declare const reactNative: Profile<AppRoots>;

package/dist/oxlint/profiles/react-native.js

@@ -0,0 +1,18 @@
+import { appFiles, appPrefixes } from "@jameswyse/oxc-config/oxlint/preset";
+import { react } from "@jameswyse/oxc-config/oxlint/profiles";
+export const reactNative = (scope, roots) => [
+    ...react(scope, appFiles(scope, roots)),
+    {
+        files: appFiles(scope, roots),
+        plugins: ["react", "jsx-a11y"],
+        rules: { "jsx-a11y/no-autofocus": "off" },
+    },
+    {
+        files: appPrefixes(roots).flatMap((prefix) => [
+            `${prefix}App.{js,jsx,ts,tsx}`,
+            `${prefix}{app,src/app}/**/*.{js,jsx,ts,tsx}`,
+        ]),
+        excludeFiles: scope.tests,
+        rules: { "import/no-default-export": "off" },
+    },
+];

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@airteam/oxc-config",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Airteam's Oxlint and Oxfmt configs for TypeScript and JavaScript projects",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/airteamaus/oxc-config.git"
+  },
+  "files": [
+    "dist",
+    "tsconfig.base.json"
+  ],
+  "type": "module",
+  "exports": {
+    "./oxlint": "./dist/oxlint/config.js",
+    "./oxfmt": "./dist/oxfmt/config.js",
+    "./tsconfig": "./tsconfig.base.json"
+  },
+  "dependencies": {
+    "@jameswyse/oxc-config": "1.0.0"
+  },
+  "devDependencies": {
+    "@changesets/cli": "3.0.3",
+    "@types/node": "^22.20.5",
+    "oxfmt": "0.77.0",
+    "oxlint": "1.92.0",
+    "oxlint-tsgolint": "7.0.2006",
+    "typescript": "7.0.2"
+  },
+  "peerDependencies": {
+    "oxfmt": ">=0.71.0 <1",
+    "oxlint": ">=1.86.0 <2",
+    "oxlint-tsgolint": ">=7.0.2003 <8"
+  },
+  "peerDependenciesMeta": {
+    "oxfmt": {
+      "optional": true
+    },
+    "oxlint-tsgolint": {
+      "optional": true
+    }
+  },
+  "devEngines": {
+    "packageManager": {
+      "name": "pnpm",
+      "version": "12.18.0"
+    },
+    "runtime": {
+      "name": "node",
+      "version": "26.13.0",
+      "onFail": "download"
+    }
+  },
+  "engines": {
+    "node": ">=22.23.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "pnpm test && pnpm lint && pnpm typecheck && pnpm format:check && pnpm build",
+    "format": "oxfmt .",
+    "format:check": "oxfmt --check .",
+    "lint": "oxlint .",
+    "test": "node --test \"src/**/*.test.ts\"",
+    "typecheck": "tsc"
+  }
 }

package/tsconfig.base.json

@@ -0,0 +1,3 @@
+{
+  "extends": "@jameswyse/oxc-config/tsconfig"
+}