@trestleinc/convex-oxlint

Oxlint plugin with Convex-specific linting rules. A faster alternative to @convex-dev/eslint-plugin.

Why?

• 50-100x faster than ESLint
• Same rules as @convex-dev/eslint-plugin
• Works with both Oxlint and ESLint (via eslintCompatPlugin)

Installation

bun add -D @trestleinc/convex-oxlint oxlint

Quick Setup

Create .oxlintrc.json in your project root:

{
  "$schema": "https://raw.githubusercontent.com/oxc-project/oxc/main/npm/oxlint/configuration_schema.json",
  "plugins": ["typescript", "import"],
  "jsPlugins": ["@trestleinc/convex-oxlint"],
  "rules": {
    "convex/no-old-registered-function-syntax": "error",
    "convex/require-args-validator": "error",
    "convex/explicit-table-ids": "error",
    "convex/import-wrong-runtime": "error"
  },
  "ignorePatterns": [
    "**/dist/**",
    "**/_generated/**",
    "**/*.d.ts",
    "**/node_modules/**"
  ]
}

File Scoping

All rules automatically scope themselves to Convex files. A file is considered a Convex file if either:

1. Its path contains a convex/ directory segment (covers standard app-level Convex code), or
2. Any ancestor directory contains a convex.config.ts or convex.config.js file (covers Convex component libraries whose source lives outside a convex/ directory).

Results are cached per-directory so the filesystem walk is not repeated.

Additionally:

• _generated/ files are always skipped.
• Rules that only apply to entry points (no-old-registered-function-syntax, import-wrong-runtime) also skip non-entry-point files (dotfiles, schema.ts, files with multiple dots in the name, etc.).

Rules

convex/no-old-registered-function-syntax

Prefer object syntax for registered Convex functions. Only fires on exported registrar calls in entry-point files.

// Bad
export const get = query(async (ctx) => {
  return ctx.db.query("users").collect();
});

// Good
export const get = query({
  args: {},
  handler: async (ctx) => {
    return ctx.db.query("users").collect();
  },
});

Auto-fix: Wraps the function in { args: {}, handler: ... } object syntax. If the old function already has an args parameter (2+ params), the fix omits args: {} so that require-args-validator can flag it separately.

convex/require-args-validator

Require args validator for Convex functions. Only fires on exported registrar calls.

// Bad
export const get = query({
  handler: async (ctx) => { ... },
});

// Good
export const get = query({
  args: { id: v.id("users") },
  handler: async (ctx, { id }) => { ... },
});

Options:

{
  "convex/require-args-validator": [
    "error",
    { "ignoreUnusedArguments": false }
  ]
}

• ignoreUnusedArguments (default false): When true, don't require an args validator when the handler function does not declare a second parameter (or declares an empty destructured {}).

Auto-fix: When the handler doesn't use args, inserts args: {}, into the config object. When the handler does use args, no auto-fix is provided since the validator type must be specified manually.

convex/explicit-table-ids

Require explicit table names in database operations (Convex 1.31+).

// Bad
await ctx.db.get(id);
await ctx.db.patch(id, { name: "new" });
await ctx.db.replace(id, doc);
await ctx.db.delete(id);

// Good
await ctx.db.get("users", id);
await ctx.db.patch("users", id, { name: "new" });
await ctx.db.replace("users", id, doc);
await ctx.db.delete("users", id);

Note: Unlike the ESLint version, this rule uses pattern matching only (no TypeScript type information). It detects ctx.db.method(...) calls by argument count and does not provide auto-fix since the table name cannot be inferred without type info.

convex/import-wrong-runtime

Detects files that use the Convex JavaScript runtime but import a "use node" module. Only "use node" files are allowed to import other "use node" files.

// helper.ts — has "use node" directive
"use node";
import { SomeNodeApi } from "some-node-lib";
export function doNodeStuff() { ... }

// query.ts — uses Convex JS runtime (no "use node")
import { doNodeStuff } from "./helper"; // ERROR: wrong runtime import

How it works:

1. Only runs on entry-point files inside convex/ directories.
2. Checks each relative import by resolving the file path and reading the first 200 characters to look for a "use node" directive.
3. If the current file itself has "use node", all imports are allowed.
4. Non-relative imports (bare specifiers like "convex/server") are not checked.

Supported Function Types

The plugin recognizes all Convex function registration methods:

• query / internalQuery
• mutation / internalMutation
• action / internalAction
• httpAction

ESLint Compatibility

This plugin uses eslintCompatPlugin from @oxlint/plugins, making it compatible with both Oxlint and ESLint. When used with Oxlint, it automatically benefits from the faster createOnce API. When used with ESLint, it falls back to the standard create API.

Migrating from ESLint

1. Remove ESLint dependencies:

bun remove eslint typescript-eslint @convex-dev/eslint-plugin

2. Add oxlint:

bun add -D @trestleinc/convex-oxlint oxlint

3. Delete eslint.config.js / eslint.config.mjs

4. Create .oxlintrc.json (see Quick Setup above)

5. Update lint scripts in package.json

License

MIT