Skip to content
Pocket Region

Getting started

Install

Section titled “Install”
Terminal window
npm install pocket-region

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

Pocket Region needs WebAssembly JSPI, so it runs on Node 24.20 or later, Chrome and Edge 137, Firefox 153, and Safari 27. In a browser without JSPI, createRegion throws.

In Node

Section titled “In Node”
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();

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.

In Node those two 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) });

In a page

Section titled “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. A page has no environment to take credentials from, so clientConfig is how a client gets them there. 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();


A first visit downloads about 15 MB: 11 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.