Revamp clerk-sdk-node build

[nikosdouvlis]

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

Packages affected

• @clerk/clerk-js
• @clerk/clerk-react
• @clerk/nextjs
• @clerk/remix
• @clerk/types
• @clerk/themes
• @clerk/localizations
• @clerk/clerk-expo
• @clerk/backend
• @clerk/backend-core
• @clerk/clerk-sdk-node
• @clerk/edge
• @clerk/shared
• build/tooling/chore

Description

• npm test runs as expected.
• npm run build runs as expected.

This PR introduces changes to the build process of the clerk/clerk-sdk-node package. Specifically,

• Transpile and bundle the package using tsup instead of tsc
• Correctly export the /esm and /cjs paths while retaining their default exports
• Introduce the exports field in package.json in preparation for clerk/clerk-sdk-node@5

Supporting all possible host app build configurations (module vs commonjs, pure JS vs TS, and the various moduleResolution strategies that can be used by TS) without introducing breaking changes to the exports of this package is impossible right now.

This PR correctly supports the APIs we've exported so far, with slight modifications that should improve compatibility with the latest node and TS versions.

Currently, the following formats are supported. Any other config combinations the host app package.json / tsconfig files should be invalid, except for the single scenario described in the Caveats section which is a valid config but cannot be supported by clerk-sdk-node currently.

1. Host application configured as a module, or Clerk is used within a module file

This scenario includes one of the following cases:

• Clerk is used within a .mjs file, or
• Clerk is used within a .js file and host app's package.json includes "type": "module"

import { users } from '@clerk/clerk-sdk-node'
import Clerk from '@clerk/clerk-sdk-node/esm/instance'

(async () => {
    const clerk = new Clerk({ apiKey: 'test_HoVeVf9Y5cEYZcMXcLDJaljNFUOlCvyNy6'})
    console.log("instance",(await clerk.users.getUserList()).length);
    console.log("direct",(await users.getUserList()).length);
})()

2. Host application configured as a commonjs package, or Clerk is used within a commonjs file

This scenario includes one of the following cases:

• Clerk is used within a .cjs file, or
• Clerk is used within a .js file and host app's package.json includes "type": "commonjs" or it does not explicitly specify a type

const { users } = require('@clerk/clerk-sdk-node');
const pkg = require("@clerk/clerk-sdk-node/cjs/instance");
const Clerk = pkg.default;

(async () => {
    const clerk = new Clerk({ apiKey: 'test_HoVeVf9Y5cEYZcMXcLDJaljNFUOlCvyNy6'})
    console.log("instance",(await clerk.users.getUserList()).length);
    console.log("direct",(await users.getUserList()).length);
})()

3. Host application is configured as a module and is using TS

• package.json includes "type": "module"
• tsconfig.json sets "module": "ESNext" (or other module strategies)
• tsconfig.json sets "moduleResolution": "Node"

With the above settings, the generated js file will be a module file. The user can import from /esm and use Clerk directly:

import Clerk from '@clerk/clerk-sdk-node/esm/instance';
const clerk = new Clerk({ apiKey: 'test_HoVeVf9Y5cEYZcMXcLDJaljNFUOlCvyNy6'})

Although unusual, importing a commonjs module is also supported in this case because the generated file is a module. The user can import Clerk from /cjs but they'll need to also use the .default prop:

import Clerk from '@clerk/clerk-sdk-node/cjs/instance';
const clerk = new Clerk.default({ apiKey: 'test_HoVeVf9Y5cEYZcMXcLDJaljNFUOlCvyNy6'})

4. Host application is configured as a commonjs package and is using TS

• package.json includes "type": "commonjs"
• tsconfig.json sets "module": "Commonjs" (or other commonjs strategies)
• tsconfig.json sets "moduleResolution": "Node"

With the above settings, the generated js file will be a commonjs file. The user can import from /cjs and use Clerk directly:

import Clerk from '@clerk/clerk-sdk-node/cjs/instance';
const clerk = new Clerk({ apiKey: 'test_HoVeVf9Y5cEYZcMXcLDJaljNFUOlCvyNy6'})

Caveats

If the host package uses TS and sets "moduleResolution": "NodeNext" or "moduleResolution": "Node16" in tsconfig.json, the types for the default import will not be correctly inferred, so TS will throw an error during compilation even though the runtime value is correct. If these two new module resolution strategies are used, TS will respect the exports field in package.json, however the correct types will not always be inferred because our package exports both default and named exports which are handled differently in ESM and CJS modules.

Possible solutions for the above:

1. Export 2 builds (cjs, esm) and 2 different sets of types (cjs, esm). Rename the ESM d.ts to d.mts manually so they are always handled as modules.
2. Drop support for CJS completely
3. Stop using default exports and stick to using explicitly named exports always.

Plan for v5

v5 will be released once we finish refactoring the package to use the new backend package. I'd suggest we also refactor our exports according to option 3 at the same time, because it is a breaking change.

What we need to do:

1. Replace default with named exports
2. Add the following exports field:

  "exports": {
    ".": {
      "types": "./dist/types/index.d.ts",
      "require": "./dist/index.js",
      "import": "./dist/index.mjs",
      "default": "./dist/index.js"
    },
    "./instance": {
      "types": "./dist/types/instance.d.ts",
      "require": "./dist/instance.js",
      "import": "./dist/instance.mjs",
      "default": "./dist/instance.js"
    }
  },

What will change:

• The /cjs and /esm paths will no longer be needed
• A single / and /instnace path would handle both esm and cjs formats automatically through the exports field
• Complete TS support even with the newest module resolution strategies through the exports field

Let me hear your thoughts, happy to discuss further :)

[dimkl]

❓ why is minify: false ?

[dimkl]

✂️