BREAKING(shared): Revamp package to use subpaths (#1898)

* chore(shared): Smaller package.json maintenance * chore(repo): Remove testUtils from shared pkg * chore(shared): Update package.json more * chore(shared): Jest cleanup * chore(shared): Move noop to root * chore(shared): Move browser and remove duplicate inClientSide helper * chore(shared): Move method helpers into "underscore" file * chore(shared): Move url to root * chore(shared): Fix jest testRegex * chore(shared): Tsup updates * chore(shared): Move color into single file * chore(shared): Move proxy to root * chore(shared): Move error stuff into error dir * chore(shared): Move date to root * chore(shared): Move keys to root * chore(shared): Move deprecated to root * chore(shared): Move isomorphicAtob to root * chore(shared): Move cookie to folder * chore(shared): Move workerTimers * chore(shared): Move file and remove mimeTypeExtensions * chore(shared): Move cookie and globs * chore(shared): Tsup ignore test files * chore(shared): Move rest of files to root * chore(shared): Re-organize hooks folder * chore(shared): Correct tsup output + exports map * chore(shared): Add minimal README * fix(backend): Update imports * chore(shared): Put error into one file + add react & react/hooks subpath * fix(clerk-js): Update imports * fix(clerk-expo): Updat imports * fix(fastify): Update imports * fix(gatsby): Update imports * fix(next): Update imports * fix(react): Update imports * fix(remix): Update imports * chore(shared): Rename and move multiDomain * fix(sdk-node): Use new imports * update lock file * fix(clerk-js): Adjust webpack config * chore(repo): Make TS compilation work with TS 5 * fix(clerk-sdk-node): Remove incorrect type key in package.json * chore(backend): Fix tests * chore(shared): Provide better backwards comp * Create wild-carrots-reply.md * chore(clerk-js): Typo fix * lol * chore(shared): Use "bundle: true" * chore(repo): Update lock file * chore(shared): Move react/hooks into react * Update wild-carrots-reply.md * fix(shared): Use correct entries for tsup * chore(repo): Add changelog entry * chore(clerk-js): Add comment
clerk · Oct 19, 2023 · aa4cd76 · aa4cd76
1 parent e5ac37e
commit aa4cd76
Show file tree

Hide file tree

Showing 164 changed files with 676 additions and 624 deletions.
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,