wesa

library0.7.1jsnpmunverified

Wesa is a CLI and library for performing storage schema migrations in browser extensions (Chrome/Firefox) packaged with webpack. The current stable version is 0.7.1, released sparsely. It helps manage storage revisions using a revision repository, similar to database migrations. Unlike generic migration tools, it targets browser.storage (local, session, sync) and integrates with webpack code splitting via dynamic imports. It requires Node.js >=24.0.0 and expects background scripts to call the migrate function with a context object.

storage devops

npm install wesa

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WESA

wesa

storagejavascriptv0.7.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

migrate

✓ import { migrate } from 'wesa'

✗ const migrate = require('wesa')

The package is ESM-only due to Node >=24.0.0 requirement.

Wesa CLI

✓ npx wesa init

✗ npx wesa migrate

This is a CLI tool, not a programmatic function. Use 'wesa init' and 'wesa revision' commands.

Context object

✓ import { migrate } from 'wesa'; await migrate(context, { area })

✗ await migrate({ getAvailableRevisions, getCurrentRevision, getRevision })

The context must be an object with three async functions; the second argument is an options object with 'area'.

This shows the typical setup: initializing the repository, creating a revision, and applying migration in a browser extension background script.

// Initialize revision repository npx wesa init npx wesa revision -m "Initial schema" // In background script: import { migrate } from 'wesa'; async function init() { const context = { getAvailableRevisions: async ({ area } = {}) => (await import('storage/config.json', { with: { type: 'json' } })).default .revisions[area], getCurrentRevision: async ({ area } = {}) => (await browser.storage[area].get('storageVersion')).storageVersion, getRevision: async ({ area, revision } = {}) => import(`storage/revisions/${area}/${revision}.js`) }; await migrate(context, { area: 'local' }); } init();

Debug

Known issues

breakingRequires Node.js >=24.0.0

fix

Update Node.js to >=24.0.0 or downgrade to an earlier version (if available).

affects: >=0.7.1

gotchaThe context functions must return correct types and be async; errors may be subtle if getAvailableRevisions returns undefined.

fix

Ensure each context function returns a Promise with the expected shape: getAvailableRevisions returns array of revision numbers, getCurrentRevision returns number or undefined, getRevision returns module with default export function.

affects: >=0.0.0

gotchaThe revision module must export a default function named 'upgrade' - any other export name will be ignored.

fix

Use 'export default async function upgrade() { ... }' in revision files.

affects: >=0.0.0

gotchaThe package uses dynamic import with import assertions (import(... , {with: {type: 'json'}})) which requires modern browser/webpack support.

fix

Ensure your webpack config and target browser support import assertions, or adjust the context function to use fetch or XMLHttpRequest.

affects: >=0.7.1

gotchaThe migration process does not handle multiple storage areas in a single call; you must call migrate for each area separately.

fix

Loop over areas: await migrate(context, { area: 'local' }); await migrate(context, { area: 'sync' }); etc.

affects: >=0.0.0

Errors

Common errors & fixes

Error: Cannot find module 'storage/config.json'

The context function getAvailableRevisions tries to import a JSON file that does not exist.

fix

Ensure you have run 'wesa init' to create the storage/config.json file and that it exports the revisions object.

TypeError: context.getAvailableRevisions is not a function

The context object passed to migrate does not have the required async functions.

fix

Provide an object with getAvailableRevisions, getCurrentRevision, and getRevision as async functions.

SyntaxError: The requested module 'wesa' does not provide an export named 'default'

Attempting default import import wesa from 'wesa' instead of named import.

fix

Use import { migrate } from 'wesa'.

Error: No revisions to migrate

The getAvailableRevisions returns an empty array or undefined for the specified area.

fix

Create at least one revision with 'wesa revision -m "message"' and ensure getAvailableRevisions returns it.

Upgrade

Version history

0.7.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

38 hits · last 30 days

node

Resources

githubhttps://github.com/dessant/wesa ↗

packagewesa ↗

homepagehttps://github.com/dessant/wesa ↗