{"id":49745,"library":"wesa","title":"Wesa","description":"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.","status":"active","version":"0.7.1","language":"javascript","source_language":"en","source_url":"https://github.com/dessant/wesa","tags":["javascript","browser extensions","web extensions","storage","versioning","migration","revisions","schema"],"install":[{"cmd":"npm install wesa","lang":"bash","label":"npm"},{"cmd":"yarn add wesa","lang":"bash","label":"yarn"},{"cmd":"pnpm add wesa","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package is ESM-only due to Node >=24.0.0 requirement.","wrong":"const migrate = require('wesa')","symbol":"migrate","correct":"import { migrate } from 'wesa'"},{"note":"This is a CLI tool, not a programmatic function. Use 'wesa init' and 'wesa revision' commands.","wrong":"npx wesa migrate","symbol":"Wesa CLI","correct":"npx wesa init"},{"note":"The context must be an object with three async functions; the second argument is an options object with 'area'.","wrong":"await migrate({ getAvailableRevisions, getCurrentRevision, getRevision })","symbol":"Context object","correct":"import { migrate } from 'wesa'; await migrate(context, { area })"}],"quickstart":{"code":"// Initialize revision repository\nnpx wesa init\nnpx wesa revision -m \"Initial schema\"\n\n// In background script:\nimport { migrate } from 'wesa';\n\nasync function init() {\n  const context = {\n    getAvailableRevisions: async ({ area } = {}) =>\n      (await import('storage/config.json', { with: { type: 'json' } })).default\n        .revisions[area],\n    getCurrentRevision: async ({ area } = {}) =>\n      (await browser.storage[area].get('storageVersion')).storageVersion,\n    getRevision: async ({ area, revision } = {}) =>\n      import(`storage/revisions/${area}/${revision}.js`)\n  };\n\n  await migrate(context, { area: 'local' });\n}\n\ninit();","lang":"typescript","description":"This shows the typical setup: initializing the repository, creating a revision, and applying migration in a browser extension background script."},"warnings":[{"fix":"Update Node.js to >=24.0.0 or downgrade to an earlier version (if available).","message":"Requires Node.js >=24.0.0","severity":"breaking","affected_versions":">=0.7.1"},{"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.","message":"The context functions must return correct types and be async; errors may be subtle if getAvailableRevisions returns undefined.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use 'export default async function upgrade() { ... }' in revision files.","message":"The revision module must export a default function named 'upgrade' - any other export name will be ignored.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Ensure your webpack config and target browser support import assertions, or adjust the context function to use fetch or XMLHttpRequest.","message":"The package uses dynamic import with import assertions (import(... , {with: {type: 'json'}})) which requires modern browser/webpack support.","severity":"gotcha","affected_versions":">=0.7.1"},{"fix":"Loop over areas: await migrate(context, { area: 'local' }); await migrate(context, { area: 'sync' }); etc.","message":"The migration process does not handle multiple storage areas in a single call; you must call migrate for each area separately.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"search_vec":"'0.7.1':25 '24.0.0':63 'background':66 'browser':14,78 'browser.storage':47 'call':69 'chrome/firefox':16 'cli':5 'code':55 'context':75 'current':21 'databas':39 'dynam':58 'expect':65 'extens':15,79,81 'function':72 'generic':42 'help':29 'import':59 'integr':52 'javascript':77 'librari':7 'local':48 'manag':30 'migrat':12,40,43,71,84 'node.js':62 'object':76 'packag':17 'perform':9 'releas':26 'repositori':36 'requir':61 'revis':32,35,85 'schema':11,86 'script':67 'session':49 'similar':37 'spars':27 'split':56 'stabl':22 'storag':10,31,82 'sync':50 'target':46 'tool':44 'unlik':41 'use':33 'version':23,83 'via':57 'web':80 'webpack':19,54 'wesa':1,2","created_at":"2026-06-07T17:03:23.866492+00:00","updated_at":"2026-06-07T17:03:23.866492+00:00","problems":[{"fix":"Ensure you have run 'wesa init' to create the storage/config.json file and that it exports the revisions object.","cause":"The context function getAvailableRevisions tries to import a JSON file that does not exist.","error":"Error: Cannot find module 'storage/config.json'"},{"fix":"Provide an object with getAvailableRevisions, getCurrentRevision, and getRevision as async functions.","cause":"The context object passed to migrate does not have the required async functions.","error":"TypeError: context.getAvailableRevisions is not a function"},{"fix":"Use import { migrate } from 'wesa'.","cause":"Attempting default import import wesa from 'wesa' instead of named import.","error":"SyntaxError: The requested module 'wesa' does not provide an export named 'default'"},{"fix":"Create at least one revision with 'wesa revision -m \"message\"' and ensure getAvailableRevisions returns it.","cause":"The getAvailableRevisions returns an empty array or undefined for the specified area.","error":"Error: No revisions to migrate"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/dessant/wesa","github":"https://github.com/dessant/wesa","docs":null,"changelog":null,"pypi":null,"npm":"wesa","openapi_spec":null,"status_page":null,"smithery":null,"categories":["storage","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}