Get started with DBOPFS

Before installation

Requirements

DBOPFS is a browser-only ES module. It expects the web platform, not Node.js, a server runtime, or server-side rendering.

Requirement	Why it matters
HTTPS or localhost	OPFS is exposed only in a secure browser context.
`navigator.storage.getDirectory`	Opens the origin-private filesystem root.
ES modules	The runtime uses imports, top-level await, private fields, and `import.meta.url`.
Window and Worker APIs	The singleton lives on `window`; a co-located worker supplies the synchronous-access fallback.
Compression and image APIs	Required only for PNG backup and restore, not ordinary CRUD.

Browser support is capability-based. Test the actual browsers you support. The playground reports each required feature independently.

Step one

Choose npm or the GitHub release.

Both sources contain the same verified dbopfs@1.0.0 package layout.

Install from npm

Use the registry when npm already manages your application's dependencies.

npm install dbopfs@1.0.0

Open dbopfs@1.0.0 on npm

Download from GitHub

Use the release tarball when you want plain self-hosted browser files without adding npm to the application.

Download dbopfs-1.0.0.tgz

curl -fL https://github.com/TheWizardNexus/DBOPFS/releases/download/v1.0.0/dbopfs-1.0.0.tgz -o dbopfs-1.0.0.tgz
mkdir -p vendor/dbopfs
tar -xzf dbopfs-1.0.0.tgz -C vendor/dbopfs --strip-components=1

Invoke-WebRequest 'https://github.com/TheWizardNexus/DBOPFS/releases/download/v1.0.0/dbopfs-1.0.0.tgz' -OutFile 'dbopfs-1.0.0.tgz'
New-Item -ItemType Directory -Force 'vendor/dbopfs' | Out-Null
tar -xzf 'dbopfs-1.0.0.tgz' -C 'vendor/dbopfs' --strip-components=1

Run either command set from the web-project root. It removes the archive's outer package/ directory while preserving the complete DBOPFS package beneath vendor/dbopfs/.

Release notes, checksums, and evidence

Verified release. The npm package and GitHub asset are the same tarball. Test, coverage, checksum, and clean-install evidence are linked from the status page.

Step two

Declare one stable application ID.

Add the declaration before importing DBOPFS. IDs must begin with a lowercase letter, contain only lowercase letters, digits, and single hyphen-separated segments, and be no longer than 64 characters.

<meta name="arcane-app-id" content="my-app">

That declaration maps browser data to:

apps/my-app/

Arcane host behavior: when the native Arcane.app.current() binding exists, its application ID is authoritative. A mismatch with the document declaration fails before storage opens.

Step three

Expose the package root to the browser.

The package contains browser files, but your web server still decides their public URL. Expose the complete package root at a stable URL such as /vendor/dbopfs/. This preserves the adjacent worker and the package's bundled runtime dependency.

import '/vendor/dbopfs/arcane/modules/DBOPFS.js';

Whether the files came from npm or the GitHub release, the public directory must keep this shape:

/vendor/dbopfs/
├── arcane/modules/
│   ├── AppDataScope.js
│   ├── DBOPFS.js
│   └── DBOPFSWorker.js
└── node_modules/strong-type/
    └── index.js

Do not flatten the package. DBOPFSWorker.js must remain beside DBOPFS.js, and the bundled node_modules/strong-type path must remain below the same package root.

Step four

Wait for the singleton.

Importing the module creates window.dbopfs and starts initialization. Awaiting its persistent readiness promise avoids an event-listener race.

import '/vendor/dbopfs/arcane/modules/DBOPFS.js';

await window.dbopfs.readyPromise;

console.log(window.dbopfs.applicationId);
console.log(window.dbopfs.storagePath);

If event-based orchestration fits your application better, guard the event with the persistent ready flag:

function begin(){
    if(!window.dbopfs?.ready){
        return;
    }

    // Initialize the application once.
}

window.addEventListener('dbopfs-ready',begin,{once:true});
begin();

Step five

Write and read JSON.

Use a .json filename when you want get() to parse stored JSON back into an object.

const db=window.dbopfs;

await db.set(
    'users',
    'alex.json',
    {
        name:'Alex',
        role:'admin'
    }
);

const user=await db.get('users','alex.json');
console.log(user.role); // "admin"

Record created: the value now lives at apps/my-app/users/alex.json inside this origin's private filesystem.

Next, learn the data formats and batch operations in Guides, or inspect every signature in the API reference.

Common first-run failures

Troubleshooting

Symptom	Check
`APP_DATA_SCOPE_REQUIRED`	Add the application-ID metadata before the module import.
`APP_DATA_SCOPE_INVALID`	Use the canonical lowercase, hyphen-separated ID format.
`APP_DATA_SCOPE_MISMATCH`	Make the document declaration match the native or explicit application identity.
`APP_DATA_STORAGE_UNAVAILABLE`	Use HTTPS or localhost and a browser exposing `navigator.storage.getDirectory`.
Worker request is 404	Keep `DBOPFSWorker.js` beside the imported `DBOPFS.js` file.
Object comes back as text	Use a filename ending in `.json`; parsing is extension-driven.
Module dependency is 404	Verify the installed package includes its bundled `strong-type` path and that the server exposes it.