clerk · LekoArts · Oct 19, 2023 · Oct 12, 2023 · Oct 12, 2023 · Oct 12, 2023
diff --git a/.changeset/wild-carrots-reply.md b/.changeset/wild-carrots-reply.md
@@ -0,0 +1,61 @@
+---
+"@clerk/shared": major
+---
+
+The package was reworked to allow for better isomorphic use cases and ESM support, resulting in some breaking changes. It now allows for [subpath exports](https://nodejs.org/api/packages.html#subpath-exports) and restricts some imports to specific subpaths.
+
+Instead of importing from the root `@clerk/shared` import you can now use subpaths for most things:
+
+```diff
+- import { deprecated, OrganizationProvider } from "@clerk/shared"
++ import { deprecated } from "@clerk/shared/deprecated"
++ import { OrganizationProvider } from "@clerk/shared/react"
+```
+
+By using subpaths you can tell bundlers to only bundle specific parts, potentially helping with tree-shaking. It also mitigates issues where e.g. modules only relevant for React where picked up in Node.js-only environments.
+
+If you're not using `@clerk/shared` directly (only by proxy through e.g. `@clerk/clerk-react`) you don't need to do anything. If you are relying on `@clerk/shared`, please read through the breaking changes below and change your code accordingly. You can rely on your IDE to give you hints on which exports are available at `@clerk/shared` and `@clerk/shared/<name>` subpaths.
+
+**Breaking Changes**
+
+- `@clerk/shared` was and still is a dual CJS/ESM package. The ESM files provided by `@clerk/shared` now use `.mjs` file extensions and also define them in their import paths, following the ESM spec. Your bundler should handle this for you.
+- Some imports where moved from the root `@clerk/shared` import to isolated subpaths.
+ - Helper utils for cookies and globs:
+
+ ```diff
+ - import { createCookieHandler, globs } from "@clerk/shared"
+ + import { createCookieHandler } from "@clerk/shared/cookie"
+ + import { globs } from "@clerk/shared/globs"
+ ```
+ - Everything related to React. Below is a small example and the full list of exports:
+
+ ```diff
+ - import { useSafeLayoutEffect, ClerkInstanceContext } from "@clerk/shared"
+ + import { useSafeLayoutEffect, ClerkInstanceContext } from "@clerk/shared/react"
+ ```
+
+ Full list of exports moved to `@clerk/shared/react`:
+
+ ```ts
+ export {
+ ClerkInstanceContext,
+ ClientContext,
+ OrganizationContext,
+ OrganizationProvider,
+ SessionContext,
+ UserContext,
+ assertContextExists,
+ createContextAndHook,
+ useClerkInstanceContext,
+ useClientContext,
+ useOrganization,
+ useOrganizationContext,
+ useOrganizationList,
+ useOrganizations,
+ useSafeLayoutEffect,
+ useSessionContext,
+ useUserContext
+ }
+ ```
+
+If you run into an issues that might be a bug, please [open a bug report](https://github.com/clerkinc/javascript/issues/new?assignees=&labels=needs-triage&projects=&template=BUG_REPORT.yml) with a minimal reproduction.
diff --git a/package-lock.json b/package-lock.json
diff --git a/packages/backend/src/api/endpoints/OrganizationApi.ts b/packages/backend/src/api/endpoints/OrganizationApi.ts
@@ -1,4 +1,4 @@
-import { deprecated } from '@clerk/shared';
+import { deprecated } from '@clerk/shared/deprecated';
 
 import runtime from '../../runtime';
 import { joinPaths } from '../../util/path';

diff --git a/packages/backend/src/index.ts b/packages/backend/src/index.ts
@@ -1,4 +1,4 @@
-import { deprecatedObjectProperty } from '@clerk/shared';
+import { deprecatedObjectProperty } from '@clerk/shared/deprecated';
 
 import type { CreateBackendApiOptions } from './api';
 import { createBackendApiClient } from './api';

diff --git a/packages/backend/src/runtime/index.ts b/packages/backend/src/runtime/index.ts
@@ -12,9 +12,9 @@
  * TODO: Support TS runtime modules
  */
 
-// @ts-expect-error
+// @ts-ignore - These are package subpaths
 import crypto from '#crypto';
-// @ts-expect-error
+// @ts-ignore - These are package subpaths
 import * as fetchApisPolyfill from '#fetch';
 
 const {

diff --git a/packages/backend/src/tokens/authObjects.ts b/packages/backend/src/tokens/authObjects.ts
@@ -1,4 +1,4 @@
-import { deprecated } from '@clerk/shared';
+import { deprecated } from '@clerk/shared/deprecated';
 import type { ActClaim, JwtPayload, ServerGetToken, ServerGetTokenOptions } from '@clerk/types';
 
 import type { Organization, Session, User } from '../api';

diff --git a/packages/backend/src/tokens/jwt/verifyJwt.ts b/packages/backend/src/tokens/jwt/verifyJwt.ts
@@ -1,4 +1,4 @@
-import { deprecatedObjectProperty } from '@clerk/shared';
+import { deprecatedObjectProperty } from '@clerk/shared/deprecated';
 import type { Jwt, JwtPayload } from '@clerk/types';
 
 // DO NOT CHANGE: Runtime needs to be imported as a default export so that we can stub its dependencies with Sinon.js

diff --git a/packages/backend/src/util/shared.ts b/packages/backend/src/util/shared.ts
@@ -6,11 +6,10 @@ export {
  isDevelopmentFromApiKey,
  isProductionFromApiKey,
  parsePublishableKey,
- deprecated,
- deprecatedProperty,
 } from '@clerk/shared';
+export { deprecated, deprecatedProperty } from '@clerk/shared/deprecated';
 
-import { buildErrorThrower } from '@clerk/shared';
+import { buildErrorThrower } from '@clerk/shared/error';
 // TODO: replace packageName with `${PACKAGE_NAME}@${PACKAGE_VERSION}` from tsup.config.ts
 export const errorThrower = buildErrorThrower({ packageName: '@clerk/backend' });
 

diff --git a/packages/backend/tsconfig.json b/packages/backend/tsconfig.json
@@ -2,12 +2,14 @@
  "compilerOptions": {
  "allowSyntheticDefaultImports": true,
  "baseUrl": ".",
+ "rootDir": "src",
  "declaration": true,
  "declarationMap": false,
  "esModuleInterop": true,
  "forceConsistentCasingInFileNames": true,
  "importHelpers": true,
- "moduleResolution": "node",
+ "moduleResolution": "NodeNext",
+ "module": "NodeNext",
  "noImplicitReturns": true,
  "noUnusedLocals": false,
  "noUnusedParameters": true,

diff --git a/packages/backend/tsconfig.test.json b/packages/backend/tsconfig.test.json
@@ -7,7 +7,10 @@
  "moduleResolution": "Node",
  "noImplicitAny": false,
  "outDir": "./tests/dist",
- "target": "ES2020"
+ "target": "ES2020",
+ "paths": {
+ "@clerk/shared/*": ["../shared/dist/*.js"]
+ }
  },
  "include": ["src/**/*.test.ts"],
  "exclude": ["node_modules", "dist", "src/__tests__"]

diff --git a/packages/clerk-js/src/core/clerk.ts b/packages/clerk-js/src/core/clerk.ts
@@ -3,7 +3,7 @@ import {
  addClerkPrefix,
  deprecated,
  handleValueOrFn,
- inClientSide,
+inBrowser as inClientSide,
  is4xxError,
  isHttpOrHttps,
  isLegacyFrontendApiKey,

diff --git a/packages/clerk-js/src/core/resources/Base.ts b/packages/clerk-js/src/core/resources/Base.ts
@@ -1,4 +1,4 @@
-import { isValidBrowserOnline } from '@clerk/shared';
+import { isValidBrowserOnline } from '@clerk/shared/browser';
 import type { ClerkAPIErrorJSON, ClerkResourceJSON, ClerkResourceReloadParams, DeletedObjectJSON } from '@clerk/types';
 
 import { clerkMissingFapiClientInResources } from '../errors';

diff --git a/packages/clerk-js/src/core/resources/DisplayConfig.ts b/packages/clerk-js/src/core/resources/DisplayConfig.ts
@@ -1,4 +1,4 @@
-import { deprecatedProperty } from '@clerk/shared';
+import { deprecatedProperty } from '@clerk/shared/deprecated';
 import type { DisplayConfigJSON, DisplayConfigResource, DisplayThemeJSON, PreferredSignInStrategy } from '@clerk/types';
 
 import { BaseResource } from './internal';

diff --git a/packages/clerk-js/src/core/resources/EmailAddress.ts b/packages/clerk-js/src/core/resources/EmailAddress.ts
@@ -1,4 +1,5 @@
-import { deprecated, Poller } from '@clerk/shared';
+import { deprecated } from '@clerk/shared/deprecated';
+import { Poller } from '@clerk/shared/poller';
 import type {
  AttemptEmailAddressVerificationParams,
  CreateEmailLinkFlowReturn,