Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Dexie Prototype Extension
✓ import 'dexie-encrypted';
✗ import { encrypt } from 'dexie-encrypted';
This import is a side-effect import that globally extends the Dexie.js prototype, adding methods like `encryptedTables()` and `encryptionKey` to all Dexie instances. No direct symbols are exported from the package itself.
Dexie
✓ import { Dexie } from 'dexie';
✗ const Dexie = require('dexie');
The core Dexie class from the peer dependency. After `dexie-encrypted` is imported, instances of this class will have the additional encryption-related methods available.
Table
✓ import { Table } from 'dexie';
✗ import { table } from 'dexie';
Used for type-safe interaction with database tables, including those marked for encryption. The encryption middleware operates at a lower level, but `Table` is crucial for typical Dexie application logic.
Demonstrates initializing a Dexie database with `dexie-encrypted` middleware, setting an encryption key, and performing encrypted `add` and `get` operations for a user record.
import { Dexie } from 'dexie';
import 'dexie-encrypted'; // This extends the Dexie prototype
// In a real application, get your key securely, e.g., from a Web Worker or IndexedDB
// DO NOT store it directly in your main application code or local storage.
const getEncryptionKey = async (): Promise<CryptoKey> => {
// For demonstration: generate a new key if not already stored in sessionStorage
let storedKey = sessionStorage.getItem('myAppEncryptionKey');
if (storedKey) {
return crypto.subtle.importKey(
'jwk',
JSON.parse(storedKey),
{ name: 'AES-GCM', length: 256 },
true,
['encrypt', 'decrypt']
);
}
const newKey = await crypto.subtle.generateKey(
{ name: 'AES-GCM', length: 256 },
true,
['encrypt', 'decrypt']
);
sessionStorage.setItem(
'myAppEncryptionKey',
JSON.stringify(await crypto.subtle.exportKey('jwk', newKey))
);
return newKey;
};
class MyEncryptedDatabase extends Dexie {
users!: Dexie.Table<{ id: number, name: string, secret: string }, number>;
constructor() {
super('MyEncryptedDatabase');
this.version(1).stores({
users: '++id, name, secret'
});
// Specify which tables contain encrypted data
this.encryptedTables(['users']);
}
}
async function runEncryptionDemo() {
const db = new MyEncryptedDatabase();
try {
// Set the encryption key. This must be done BEFORE any data operations.
db.encryptionKey = await getEncryptionKey();
// Add an encrypted user
const userId = await db.users.add({ id: 1, name: 'Alice', secret: 'Top secret info' });
console.log(`Added user with ID: ${userId}`);
// Retrieve the user. It will be decrypted automatically.
const user = await db.users.get(userId);
console.log('Retrieved user:', user);
console.log('User secret (decrypted):', user?.secret);
// Verify that the retrieved secret matches the original
if (user?.secret === 'Top secret info') {
console.log('Encryption and decryption successful!');
} else {
console.error('Decryption failed or data mismatch.');
}
} catch (error) {
console.error('Error during encryption demo:', error);
} finally {
db.close();
}
}
runEncryptionDemo();
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'encrypt') or Property 'encryptedTables' does not exist on type 'Dexie'.
The `dexie-encrypted` side-effect import was either missed or placed incorrectly, preventing the Dexie prototype from being extended.
fixEnsure `import 'dexie-encrypted';` is present at the top level of your application entry file or before any Dexie database instance is created and initialized.
Error: Encryption key missing for table 'yourTableName'.
The `db.encryptionKey` was not set, or it was `null`/`undefined` when an operation on an encrypted table was attempted.
fixCall `db.encryptionKey = await getYourSecureKey();` and ensure a valid `CryptoKey` instance is assigned before any read/write operations on encrypted tables.
Uncaught (in promise) DOMException: The key 'id' in 'yourTableName' is not unique.
Attempting to add or put an item with a duplicate primary key (e.g., `id`) into an encrypted table without proper handling, or the encryption/decryption process is interfering with key uniqueness.
fixVerify your schema's primary key (`id`) and indexes are correctly defined. If using client-side generated UUIDs, ensure they are truly unique. Review Dexie's documentation on unique keys and compound indexes.
Audit
Dependencies
dexierequiredPeer dependency; `dexie-encrypted` extends the Dexie prototype and is unusable without a Dexie instance.