Skip to content

docs: restore TypeScript external storage snippets #5217

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
lennessyy wants to merge 2 commits into
base: main
Choose a base branch
from
+28 −1
Draft

docs: restore TypeScript external storage snippets #5217

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7aca139
docs: restore external storage TypeScript snippets
lennessyy Aug 31, 2026
efb5dcf
docs: simplify custom storage snippet markers
lennessyy Aug 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 28 additions & 1 deletion docs/develop/typescript/best-practices/data-handling/external-storage.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,7 @@ tabs that follow. Only the driver setup differs between the two. Everything afte
The AWS SDK reads environment variables, an IAM role, or your AWS config file.

<!--SNIPSTART typescript-s3-driver-create-->
[features/snippets/external_storage/s3_setup/s3_driver_create.ts](https://github.com/temporalio/features/blob/main/features/snippets/external_storage/s3_setup/s3_driver_create.ts)
```ts
import { S3Client } from '@aws-sdk/client-s3';
import { S3StorageDriver } from '@temporalio/external-storage-s3';
Expand All @@ -92,6 +93,7 @@ tabs that follow. Only the driver setup differs between the two. Everything afte
The Google Cloud SDK reads Application Default Credentials.

<!--SNIPSTART typescript-gcs-driver-create-->
[features/snippets/external_storage/gcs_setup/gcs_driver_create.ts](https://github.com/temporalio/features/blob/main/features/snippets/external_storage/gcs_setup/gcs_driver_create.ts)
```ts
import { Storage } from '@google-cloud/storage';
import { GcsStorageDriver } from '@temporalio/external-storage-gcs';
Expand All @@ -118,6 +120,7 @@ tabs that follow. Only the driver setup differs between the two. Everything afte
requires:

<!--SNIPSTART typescript-s3-external-storage-setup-->
[features/snippets/external_storage/s3_setup/s3_external_storage_setup.ts](https://github.com/temporalio/features/blob/main/features/snippets/external_storage/s3_setup/s3_external_storage_setup.ts)
```ts
import { Client, Connection } from '@temporalio/client';
import { ExternalStorage } from '@temporalio/common';
Expand Down Expand Up @@ -176,6 +179,27 @@ A custom driver implements the `StorageDriver` interface, which has two readonly
string key-value pairs that the driver uses to locate the payload later.
- `retrieve()` receives the claims that `store()` produced and returns the original payloads.

The following methods batch the storage operations and stop outstanding work if one operation fails:

<!--SNIPSTART typescript-custom-storage-driver-->
[external-storage/src/filesystem-storage-driver.ts](https://github.com/temporalio/samples-typescript/blob/extstore/initial-sample/external-storage/src/filesystem-storage-driver.ts)
```ts
async store(context: StorageDriverStoreContext, payloads: Payload[]): Promise<StorageDriverClaim[]> {
const keyPrefix = buildKeyPrefix(context.target);
return runAllAbortingOnFirstError(context.abortSignal, (signal) =>
payloads.map((payload) => this.storePayload(payload, keyPrefix, signal)),
);
}

/** Inverse of {@link store}: one payload per claim, in the same order. */
async retrieve(context: StorageDriverRetrieveContext, claims: StorageDriverClaim[]): Promise<Payload[]> {
return runAllAbortingOnFirstError(context.abortSignal, (signal) =>
claims.map((claim) => this.retrievePayload(claim, signal)),
);
}
```
<!--SNIPEND-->

### 2. Store payloads

In `store()`, serialize each Payload protobuf message to bytes and write the bytes to your storage system. The
Expand All @@ -202,7 +226,8 @@ Pass your driver to an `ExternalStorage` instance on the Data Converter, and use
Client and Worker. Both sides need it: a Client without External Storage configured cannot read an offloaded result. You
can also package your driver as a [plugin](/develop/plugins-guide) for easier reuse across services:

<!--SNIPSTART typescript-custom-driver-data-converter -->
<!--SNIPSTART typescript-custom-driver-data-converter-->
[external-storage/src/data-converter.ts](https://github.com/temporalio/samples-typescript/blob/extstore/initial-sample/external-storage/src/data-converter.ts)
```ts
export function createDataConverter(rootDir: string = STORAGE_ROOT): DataConverter {
return {
Expand Down Expand Up @@ -232,6 +257,7 @@ externalize all payloads regardless of size. Payloads smaller than the threshold
compared against the threshold is that of the serialized Payload, which includes its metadata, not just your data.

<!--SNIPSTART typescript-external-storage-threshold-->
[features/snippets/external_storage/threshold/threshold_config.ts](https://github.com/temporalio/features/blob/main/features/snippets/external_storage/threshold/threshold_config.ts)
```ts
const dataConverter = {
externalStorage: new ExternalStorage({
Expand Down Expand Up @@ -265,6 +291,7 @@ The following example registers two drivers but always selects `preferredDriver`
is only registered so the Worker can retrieve payloads that were previously stored with it:

<!--SNIPSTART typescript-external-storage-multiple-drivers-->
[features/snippets/external_storage/multiple_drivers/multiple_drivers.ts](https://github.com/temporalio/features/blob/main/features/snippets/external_storage/multiple_drivers/multiple_drivers.ts)
```ts
const preferredDriver = new S3StorageDriver({
client: new AwsSdkS3StorageDriverClient(s3Client),
Expand Down