SQLocal

SQLocal makes it easy to run SQLite3 in the browser, backed by the origin private file system. It wraps the WebAssembly build of SQLite3 and gives you a simple interface to interact with databases running on device.

based on DallasHoff/sqlocal

Documentation - GitHub - NPM - Fund

What this is

I'm using Next.js with turbo, which does not yet support new Worker(). But I wanted to stay with turbo and use OPFS. So I bundled what's necessary to just include a script tag, wait for the load event and assign the database instance to a local variable that I can use with React.

How to

First install the package

npm install sqlocal-bundle

Then add a postinstall script to your package.json that copies the contents from the sqlocal-bundle package into you public folder like the following (you can also find another way):

import * as path from 'node:path';
import { fileURLToPath } from 'node:url';

import cpy from 'cpy';

const sqlocal = import.meta.resolve('sqlocal-bundle');

if (!sqlocal) {
	throw new Error('Could not resolve sqlocal-bundle');
}

const sqlocalPath = fileURLToPath(sqlocal);

const root = path.resolve(sqlocalPath, '../..', 'bundle');

await cpy(`${root}/*`, 'public/scripts/sqlocal-bundle', { flat: true });
await cpy(`${root}/sqlite-wasm`, 'public/scripts/sqlocal-bundle/sqlite-wasm', { flat: true });

Add another script in public/scripts/sqlocal.mjs that will load the sqlocal-bundle and expose a global variable:

import { SQLocalDrizzle } from './sqlocal-bundle/drizzle.mjs';

globalThis.SQLocalDrizzle = SQLocalDrizzle;

Then add a script tag to your page / layout that loads the script

import Script from 'next/script';

export default function Page() {
  const handleLoad = () => {
    // in case you use react strict mode, you should check if this was already called once ...
    const SQLocal: typeof SQLocalDrizzle = globalThis.SQLocalDrizzle;
    const { driver, sql } = new SQLocal('myopfsdatabase.sqlite3');
    
    /* use sql or driver with drizzle and continue with your code */
  }

  return (
    <>
      <Script onLoad={() => void handleLoad()} src="/static/scripts/sqlocal.mjs" type="module" />
      {/* Your page content */}
    </>
  )
}

Make sure to follow the docs for SQLocal and also don't forget that OPFS requires certain headers that can be set in your next.config.js file:

headers: async () => {
  return [
    {
      /* required for https://github.com/sqlite/sqlite-wasm */
      headers: [
        { key: 'Cross-Origin-Opener-Policy', value: 'same-origin' },
        { key: 'Cross-Origin-Embedder-Policy', value: 'require-corp' },
      ],
    },
  ];
},