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.
MindooDB
✓ import { MindooDB } from 'mindoodb';
✗ const MindooDB = require('mindoodb');
This is the primary import for Node.js environments. Ensure your project is configured for ESM. For web browsers, use the '/browser' subpath.
MindooDB (Web)
✓ import { MindooDB } from 'mindoodb/browser';
✗ import { MindooDB } from 'mindoodb';
Use this specific import for web browser environments. Attempting to use the default 'mindoodb' import in a browser might result in compatibility issues or larger bundle sizes due to Node.js-specific dependencies.
MindooDocument
✓ import { type MindooDocument } from 'mindoodb';
✗ import { MindooDocument } from 'mindoodb';
This type represents a document stored within MindooDB. Using `import type` explicitly indicates it's a type import, which can improve tree-shaking for bundlers.
This quickstart initializes MindooDB, creates a new end-to-end encrypted document, updates it, and then retrieves and decrypts the content, demonstrating basic client-side data operations without exposing plaintext to a server.
import { MindooDB, type MindooDocument } from 'mindoodb';
async function initializeAndUseMindooDB() {
// IMPORTANT: For production, manage user passwords securely and do NOT hardcode.
// This password is used to derive encryption keys for the user's data.
const userPassword = process.env.MINDOODB_PASSWORD ?? 'secure-dev-password-123';
const userId = 'my-unique-user-id'; // A unique identifier for the current user
console.log('Initializing MindooDB...');
// Instantiate MindooDB. In a real application, you'd configure a persistent
// storage adapter (e.g., IndexedDB for web) and potentially a sync service.
const db = new MindooDB({
userId: userId,
password: userPassword,
});
await db.init();
console.log(`MindooDB initialized for user: ${userId}`);
// 1. Create a new end-to-end encrypted document
console.log('Creating a new document...');
const newDocument: MindooDocument = await db.createDocument({
type: 'secret-note',
title: 'Top Secret Plan',
content: 'Phase 1: Encrypt everything. Phase 2: Distribute. Phase 3: Profit.',
tags: ['secret', 'plan', 'e2e']
});
console.log(`Document created with ID: ${newDocument.id}`);
console.log('Initial document content (decrypted client-side):', newDocument.content);
// 2. Update the document
console.log('Updating the document...');
await newDocument.update(currentDoc => {
currentDoc.content = 'Phase 1: Encrypt everything. Phase 2: Securely distribute. Phase 3: Achieve peace.';
return currentDoc;
});
console.log('Document updated.');
// 3. Retrieve and verify the document
console.log('Retrieving the document...');
const retrievedDocument = await db.getDocument<MindooDocument>(newDocument.id);
if (retrievedDocument) {
console.log(`Retrieved document ID: ${retrievedDocument.id}`);
console.log('Retrieved document title:', retrievedDocument.title);
console.log('Retrieved document content (decrypted client-side):', retrievedDocument.content);
console.log('This data was never exposed in plaintext to any server.');
} else {
console.error('Failed to retrieve document.');
}
// In a real scenario, you would connect to a sync server to exchange
// encrypted changes with other clients, e.g., await db.sync();
}
initializeAndUseMindooDB().catch(console.error);
Errors
Common errors & fixes
ReferenceError: navigator is not defined
Attempting to use the browser-specific build of MindooDB (e.g., `mindoodb/browser`) in a Node.js environment, which lacks browser globals like `navigator`.
fixFor Node.js, ensure you import from the main package: `import { MindooDB } from 'mindoodb';`. For web browsers, explicitly import from `mindoodb/browser`. Error: Cannot find module 'react-native-automerge-generated'
A required peer dependency, specifically `react-native-automerge-generated` for React Native environments, is not installed or correctly linked.
fixEnsure `npm install react-native-automerge-generated` (and other relevant peer deps like `react-native-quick-crypto`) has been run, and follow any platform-specific linking instructions for React Native.
TypeError: WebCrypto is not defined
The runtime environment (e.g., older Node.js versions, certain browser contexts, or improperly configured Expo/React Native) lacks a global `crypto.subtle` API, which is essential for MindooDB's cryptographic operations.
fixFor Node.js, ensure you are on a recent version (>=15.0.0) or provide a suitable polyfill. For Expo/React Native, verify that `expo-standard-web-crypto` is installed and correctly configured as per its documentation.
Audit
Dependencies
expo-standard-web-cryptooptionalProvides standard Web Crypto API compatibility for Expo and React Native environments.
node-forgeoptionalProvides cryptographic primitives for Node.js environments.
react-native-automerge-generatedoptionalCore CRDT (Automerge) library specifically optimized for React Native.
react-native-quick-cryptooptionalEnhances cryptographic performance in React Native environments.
tweetnacloptionalProvides low-level cryptographic primitives.