Type mismatch with pgvector/kysely in ESM/NodeNext projects (RawBuilder CJS vs ESM)

[briandastous]

Type mismatch with pgvector/kysely in ESM/NodeNext projects (RawBuilder CJS vs ESM)

Summary

In ESM projects using moduleResolution: "NodeNext", pgvector/kysely returns a RawBuilder type that resolves to Kysely’s CJS typings, while the app resolves Kysely’s ESM typings. The two RawBuilder types are nominally identical but treated as incompatible, causing TypeScript errors.

Environment

• pgvector: ^0.2.1
• kysely: ^0.28.7
• typescript: ^5.9.3
• package.json: "type": "module"
• tsconfig: "module": "NodeNext", "moduleResolution": "NodeNext"

Repro

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true
  }
}

index.ts

import type { RawBuilder } from "kysely";
import { cosineDistance } from "pgvector/kysely";

const d: RawBuilder<number> = cosineDistance("embedding", [0, 1, 2]);

Actual

TypeScript error (paraphrased):

Type 'RawBuilder<number>' is not assignable to type 'RawBuilder<number>'.
Two different types with this name exist, but they are unrelated.

The two RawBuilder types resolve from different module paths (CJS vs ESM).

Expected

pgvector/kysely should be typed to the same Kysely entrypoint as ESM consumers, so RawBuilder is assignable.

Suggested fixes

• Ship ESM-aware typings via exports (e.g., types condition / .d.mts) for pgvector/kysely.
• Ensure the RawBuilder type in pgvector/kysely resolves to the same Kysely entrypoint as ESM consumers.

Workaround

We’re currently using a local module augmentation to force the return type to Kysely’s ESM RawBuilder. It works but is brittle.