For many users, this upgrade will not require any changes to your application code. The v6 release of @globus/sdk was considered a breaking change based on the following:
- Deprecation of support for Node.js 18. This version of Node.js has reached its end-of-life. The
@globus/sdkhas been updated to support Node.js 20 and later. - "Timer" service renamed to "Timers". The
@globus/sdk/services/timerservice has been renamed to@globus/sdk/services/timersto better reflect the rest of the Globus ecosystem. - Typescript
- Removal of the
@globus/typespackage. The@globus/typespackage has been removed from the SDK, and all types are now included in the main@globus/sdkpackage. This change was made to simplify the installation process and reduce confusion about which package to use for type definitions as the source of truth. - More complete, and accurate, service types. With service types colocated in the SDK, we've been able to utilize types generated directly from the OpenAPI specifications published by the various services.
- Removal of the
- Remove the
@globus/typespackage from your project dependencies. - Address any import statements that reference
@globus/types; These should be updated to import from@globus/sdkinstead.
- If you were using the OpenAPI types from the
@globus/typespackage, you can now import them directly from the@globus/sdkpackage. - For all other types, they have been co-located with their respective modules; The global Globus namespace should no longer be used.
-import type { components, operations } from '@globus/types/compute';
import {type OpenAPI } from '@globus/sdk/services/compute';
// OpenAPI.components === components
// OpenAPI.operations === operations-Globus.Transfer.EndpointDocument
import type { EndpointDocument } from '@globus/sdk/services/transfer/service/endpoint';The @globus/sdk/services/timer service has been renamed to @globus/sdk/services/timers. This change was made to align with the naming conventions used in the rest of the Globus ecosystem.
-import { timer } from '@globus/sdk';
+import { timers } from '@globus/sdk';-import { timer } from '@globus/sdk';
-timer.create({ /* ... */ });
+import { timers } from '@globus/sdk';
+timers.timer.create({ /* ... */ });The v5 release of @globus/sdk updates the AuthorizationManager to use an in-memory storage mechanism for tokens, moving the implementation to "secure by default".
The v4 behavior of using localStorage as the storage mecanism is now opt-in and should only be enabled when following security best practices related to Storage APIs.
To use a different storage mechanism, a well-known storage system (i.e., localStorage, sessionStorage) can be provided as the storage configuration option on creation.
authorization.create({
// ...
storage: localStorage,
});Any implementation of Storage can be provided to use a custom storage mechanism.
class MyCustomStorage implements Storage {};
authorization.create({
// ...
storage: new MyCustomStorage();
});The TokenLookup class has been renamed to TokenManager to better reflect the available methods.
-import { TokenLookup } from '@globus/sdk/core/authorization/TokenLookup';
+import { TokenManager } from '@globus/sdk/core/authorization/TokenManager';The v4 release of @globus/sdk addresses a number of issues related to the CommonJS and ESM bundle exports. Prior to this relases, many environments required the use of the CommonJS bundle (even when ESM was supported).
In addition to bundle improvements, the v4 release moves to using the native Web Crypto API for cryptographic operations during the OAuth2 PKCE (when using the AuthorizationManager). Based on the async nature of the Web Crypto API, many methods of the AuthorizationManager now return Promises.
The distributed package.json file has been overhauled to better align with the intended use of the package, and build and runtime environment expectations for sourcing modules.
From an implementation standpoint, this means you should no longer need to explicitly reference the cjs or esm directories in your path references.
-import { isConsentRequiredError } from "@globus/sdk/cjs/lib/core/errors";
+import { isConsentRequiredError } from "@globus/sdk/core/errors";NOTE: The change above also reflects the removal of the lib directory mentioned below.
The lib directory has been removed and should no longer be used in path references.
-import { endpointManager } from '@globus/sdk/esm/lib/services/transfer';
+import { endpointManager } from '@globus/sdk/services/transfer';Explicit @globus/sdk/cjs/* references were being used to avoid issues with the ESM package (mainly incompatible exports). If your build environment does not require you to use CommonJS, most path references can be swapped with their ESM counterpart by removing /cjs/lib.
-import { endpointManager } from '@globus/sdk/cjs/lib/services/transfer';
+import { endpointManager } from '@globus/sdk/services/transfer';We are still committed to supporting CommonJS environments, but the number of entrypoints has been reduced. We believe this decision better reflects the intended usage of the CommonJS package and the fact the the entrypoints will bundle all required code to make the entrypoint viable – having deep entrypoints for individual service methods doesn't seem useful at this time.
const sdk = require('@globus/sdk');Or, explicity:
const sdk = require('@globus/sdk/cjs');In order to support the use of the native Web Crypto API, many methods of the AuthorizationManager now return Promises, impacted methods include:
AuthorizationManager.login()AuthorizationManager.handleErrorResponse()AuthorizationManager.handleAuthorizationRequirementsError()AuthorizationManager.handleConsentRequiredError()
See the AuthorizationManager documentation for full details.