A small release with a useful integration fix

The upstream changelog dates CUID2 3.3.0 to . It lists two fixes: the exported path for package.json, and a TypeScript declaration change from an export assignment to named exports to address TS1203. This is an October integration review of that release, not an announcement of a new October version. Read the upstream release notes.

The practical question is whether the package works through your application's compiler and runtime. A successful installation alone does not answer that. Our check exercises the metadata export, imports the generator through its public entry point, and applies a fixed-length application rule to the output.

Check the package you actually installed

This example was tested with Node.js 24.5.0, CUID2 3.3.0, and TypeScript 5.9.3 using both NodeNext and bundler resolution. In a disposable directory, save cuid2-upgrade-check.mts and install the versions used for this walkthrough:

Reproduce this release check
bash
npm init -y
npm install --save-exact @paralleldrive/cuid2@3.3.0
npm install --save-dev --save-exact typescript@5.9.3 @types/node@20.19.30
npx tsc --noEmit --strict --skipLibCheck false --target es2022 --module nodenext --moduleResolution nodenext cuid2-upgrade-check.mts
node cuid2-upgrade-check.mts

The .mts extension makes the example an ES module. The compiler command checks the declarations; Node runs the assertions. Neither step substitutes for the other. The file should finish with “CUID2 3.3.0: package export, generation, and schema checks passed.” These commands check version 3.3.0; they do not reproduce the compiler error in earlier releases.

The application rule inside the check
typescript
import { createId, isCuid } from "@paralleldrive/cuid2";

const acceptsProjectId = (value: unknown): value is string =>
  typeof value === "string" && value.length === 24 && isCuid(value);

const id: string = createId();
console.log(acceptsProjectId(id));   // true
console.log(acceptsProjectId("ab")); // false

In our installed package, isCuid("ab") returns true. That is acceptable to the package's broad format rule but unsuitable for a project table that requires 24 characters. Keeping an explicit length rule makes this application assumption visible during upgrades. See the implementation guide's validation examples for other strings that pass a shape check.

Coming from version 2? Check the module boundary

The same changelog records the switch to ES modules in version 3.0.0. An upgrade from version 2 therefore crosses a different boundary from an upgrade within version 3. Test your entry point, test runner, and deployment runtime together; a small scratch script cannot prove compatibility with every build pipeline. Source: the version 3 release notes.

For a bundler-based TypeScript application, also compile the downloaded file with the following settings, then run your real production build. The scratch check intentionally leaves declaration checking enabled so an ignored library error cannot produce a misleading pass.

Check bundler resolution separately
bash
npx tsc --noEmit --strict --skipLibCheck false --target es2022 --module esnext --moduleResolution bundler cuid2-upgrade-check.mts

If the isolated check passes while the application fails, compare the lockfile, TypeScript resolution settings, module format, and runtime version. If it fails in isolation, keep that small reproduction with the exact dependency versions when investigating the failure.

What this tells you about rollout

Our result supports using these public imports and the metadata export in the tested environments. It does not establish browser support, throughput, or collision resistance. Those require different checks. Pin the candidate version while evaluating it, exercise an actual create-and-read operation, and keep the package upgrade separate from changes to ID length.

Changing a library does not require rewriting stored primary keys. If you are also moving from legacy CUID v1, use the worked migration example to preserve old routes and relationships. For new schemas, the PostgreSQL walkthrough turns the fixed-length rule into a database constraint.