SQLite-WASM for RoyaleSponsor

A lightweight, robust WebAssembly build of SQLite specifically optimized for the unique state-management and performance needs of RoyaleSponsor. This implementation ensures that your client-side data persistence remains lightning-fast and entirely offline-capable, bridging the gap between local gaming states and reliable SQL performance right in the browser. The latest updates bring substantial under-the-hood improvements, addressing several critical edge cases around concurrency and memory management during intensive database operations. With these recent stability fixes in place, the engine delivers predictable connection handling and smoother transaction lifecycles, giving you a dependable data layer that just works without unexpected crashes.

Quick install

npm install git+https://github.com/royalsponsorgame/sqlite-wasm.git

https://github.com/royalsponsorgame/sqlite-wasm

SQLite Wasm

SQLite Wasm conveniently wrapped as an ES Module.

Installation

npm install @sqlite.org/sqlite-wasm

Bug reports

Warning

This project wraps the code of SQLite Wasm with no changes, apart from added TypeScript types. Please do not file issues or feature requests regarding the underlying SQLite Wasm code here. Instead, please follow the SQLite bug filing instructions. Filing TypeScript type related issues and feature requests is fine.

Node.js support

Warning

Node.js is currently only supported for in-memory databases without persistence.

Usage

There are two ways to use SQLite Wasm:

• in a worker
• in the main thread

Only the worker versions allow you to use the origin private file system (OPFS) storage back-end.

In a worker (with OPFS if available):

Warning

For this to work, you need to set the following headers on your server:

Cross-Origin-Opener-Policy: same-origin

Cross-Origin-Embedder-Policy: require-corp

// In `main.js`.
const worker = new Worker('worker.js', { type: 'module' });

// In `worker.js`.
import sqlite3InitModule from '@sqlite.org/sqlite-wasm';

const start = (sqlite3) => {
  console.log('Running SQLite3 version', sqlite3.version.libVersion);
  const db =
    'opfs' in sqlite3
      ? new sqlite3.oo1.OpfsDb('/mydb.sqlite3')
      : new sqlite3.oo1.DB('/mydb.sqlite3', 'ct');
  console.log(
    'opfs' in sqlite3
      ? `OPFS is available, created persisted database at ${db.filename}`
      : `OPFS is not available, created transient database ${db.filename}`,
  );
  // Your SQLite code here.
};

const initializeSQLite = async () => {
  try {
    console.log('Loading and initializing SQLite3 module...');
    const sqlite3 = await sqlite3InitModule();
    console.log('Done initializing. Running demo...');
    start(sqlite3);
  } catch (err) {
    console.error('Initialization error:', err.name, err.message);
  }
};

initializeSQLite();

The db object above implements the Object-Oriented API #1.

In the main thread (without OPFS):

import sqlite3InitModule from '@sqlite.org/sqlite-wasm';

const start = (sqlite3) => {
  log('Running SQLite3 version', sqlite3.version.libVersion);
  const db = new sqlite3.oo1.DB('/mydb.sqlite3', 'ct');
  // Your SQLite code here.
};
const initializeSQLite = async () => {
  try {
    console.log('Loading and initializing SQLite3 module...');
    const sqlite3 = await sqlite3InitModule();
    console.log('Done initializing. Running demo...');
    start(sqlite3);
  } catch (err) {
    console.error('Initialization error:', err.name, err.message);
  }
};

initializeSQLite();

The db object above implements the Object-Oriented API #1.

Usage with vite

If you are using vite, you need to add the following config option in vite.config.js:

import { defineConfig } from 'vite';

export default defineConfig({
  server: {
    headers: {
      'Cross-Origin-Opener-Policy': 'same-origin',
      'Cross-Origin-Embedder-Policy': 'require-corp',
    },
  },
  optimizeDeps: {
    exclude: ['@sqlite.org/sqlite-wasm'],
  },
});

Check out a sample project that shows this in action.

Demo

See the demo folder for examples of how to use this in the main thread and in a worker. (Note that the worker variant requires special HTTP headers, so it can't be hosted on GitHub Pages.) An example that shows how to use this with vite is available on StackBlitz.

Projects using this package

See the list of npm dependents for this package.

Deploying a new version

(These steps can only be executed by maintainers.)

1. Manually trigger the GitHub Actions workflow. By default, it uses the latest SQLite tag. This pull request will contain the latest sqlite3.wasm and related bindings.

2. Once the above pull request is validated and merged, update the version number in package.json, reflecting the current SQLite version number and add a build identifier suffix like -build1. The complete version number should read something like 3.41.2-build1.

Building the SQLite Wasm locally

1. Build the Docker image:

   docker build -t sqlite-wasm-builder:env .

2. Run the build:

   Unix (Linux/macOS):

   docker run --rm \
     -e SQLITE_REF="master" \
     -v "$(pwd)/out":/out \
     -v "$(pwd)/src/bin":/src/bin \
     sqlite-wasm-builder:env build

   Windows (PowerShell):

   docker run --rm `
     -e SQLITE_REF="master" `
     -v "${PWD}/out:/out" `
     -v "${PWD}/src/bin:/src/bin" `
     sqlite-wasm-builder:env build

   Windows (Command Prompt):

   docker run --rm ^
     -e SQLITE_REF="master" ^
     -v "%cd%/out:/out" ^
     -v "%cd%/src/bin:/src/bin" ^
     sqlite-wasm-builder:env build

Running tests

The test suite consists of Node.js tests and browser-based tests (using Vitest Browser Mode). Tests aim to sanity-check the exported scripts. We test for correct exports and very basic functionality.

1. Install dependencies:

   npm install

2. Install Playwright browsers (required for browser tests):

   npx playwright install chromium --with-deps --no-shell

3. Run all tests:

   npm test

Deprecations

The Worker1 and Promiser1 APIs are, as of 2026-04-15, deprecated. They will not be removed, but they also will not be extended further. It is their author's considered opinion that they are too fragile, too imperformant, and too limited for any non-toy software, and their use is actively discouraged. The "correct" way to use this library is documented in Usage section above.

License

Apache 2.0.

Acknowledgements

This project is based on SQLite Wasm, which it conveniently wraps as an ES Module and publishes to npm as @sqlite.org/sqlite-wasm.

Related searches

Developers seeking reliable relational database capabilities in web environments frequently look for robust WebAssembly ports and browser-compatible storage engines that run efficiently on the client side. When building modern architectures, they often explore complementary ecosystem scaffolding like a custom yeoman generator, lightweight backend layers using a microservice python framework with pydantic validation, or quick-start foundations such as an express boilerplate, alongside specialized utilities like a dedicated pdf generator node package.

Topics: webassembly database, browser sql storage, embedded database engine, yeoman generator, pydantic, microservice python, express boilerplate, pdf generator node, sqlite wasm port, client side database, web sql wrapper