Getting started

Pocket Region needs WebAssembly JSPI, so it runs on Chrome and Edge 137, Firefox 153, Safari 27, and Node 24.20 or later. In a browser without JSPI, createRegion rejects, and regionSupported() says so before you try.

In a page

A page loads the package from a URL. Map it in the page’s import map, from jsDelivr or from a copy of dist/ on your own site, and import it by name. Pin a version in a page you ship, such as pocket-region@1.2.3, which this example leaves out to always name the latest:

<script type="importmap">
  { "imports": { "pocket-region/browser": "https://cdn.jsdelivr.net/npm/pocket-region/dist/browser.js" } }
</script>

The page loads the emulator over HTTP, from jsDelivr by default. To serve the package’s vendor/ directory from your own site instead, map pocket-region/vendor/ to it in the same import map, or pass assetsBaseUrl. This site maps its own dist/ and vendor/, and examples with a Run button run as shown, in this tab.

import { clientConfig, createRegion } from 'pocket-region/browser';
import { S3Client, CreateBucketCommand, PutObjectCommand, GetObjectCommand } from '@aws-sdk/client-s3';

const region = await createRegion();

const s3 = new S3Client(clientConfig(region));

await s3.send(new CreateBucketCommand({ Bucket: 'photos' }));
await s3.send(new PutObjectCommand({ Bucket: 'photos', Key: 'cat.txt', Body: 'meow' }));
const { Body } = await s3.send(new GetObjectCommand({ Bucket: 'photos', Key: 'cat.txt' }));
console.log(await Body.transformToString());

await region.stop();

clientConfig is the region, throwaway credentials, and the handler that turns the client’s requests into calls on the region, as one config. The SDK refuses to build a request without a region and credentials, but any values do and nothing is dialed.

A first visit downloads about 10.8 MB: 7.1 MB of wheels and the Python standard library, already compressed, and 3.7 MB of Pyodide from jsDelivr, unless you pass indexURL. Everything else works as it does in Node, except that Lambda handlers run in Web Workers and there is no save or serve.

In Node

npm install pocket-region

The AWS SDK clients aren’t dependencies. Install the ones you use, such as @aws-sdk/client-s3.

import { clientConfig, createRegion } from 'pocket-region/node';
import { S3Client, CreateBucketCommand, PutObjectCommand } from '@aws-sdk/client-s3';

const region = await createRegion();
const s3 = new S3Client(clientConfig(region));

await s3.send(new CreateBucketCommand({ Bucket: 'photos' }));
await s3.send(new PutObjectCommand({ Bucket: 'photos', Key: 'cat.txt', Body: 'meow' }));

await region.stop();

A page has no environment to take a region and credentials from. In Node they can come from the environment or ~/.aws as usual, which leaves requestHandler as the client’s only setting:

import { requestHandler } from 'pocket-region/node';

const s3 = new S3Client({ requestHandler: requestHandler(region) });