Notesnook

https://github.com/streetwriters/notesnook
Admin
Notesnook is a free, open-source, end-to-end encrypted note-taking application that prioritizes user...
Tokens:22,163
Snippets:376
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Start development server

Source: https://github.com/streetwriters/notesnook/blob/master/apps/web/README.md

Launch the web application in development mode.

```bash
npm run start:web
```

--------------------------------

### Install dependencies

Source: https://github.com/streetwriters/notesnook/blob/master/extensions/web-clipper/README.md

Run this command in the repository root to install necessary packages.

```sh
npm install
```

--------------------------------

### Install dependencies

Source: https://github.com/streetwriters/notesnook/blob/master/apps/web/README.md

Prepare the environment by installing required packages using NPM.

```bash
# this might take a while to complete
npm install
```

--------------------------------

### Start development server

Source: https://github.com/streetwriters/notesnook/blob/master/apps/theme-builder/README.md

Launches the theme builder application in development mode.

```bash
npm run start:theme-builder
```

--------------------------------

### Install Dependencies and Bootstrap Mobile Workspace

Source: https://github.com/streetwriters/notesnook/blob/master/apps/mobile/README.md

Install project dependencies and bootstrap the mobile workspace. This command may take a significant amount of time to complete.

```bash
# this might take a while to complete
npm install
npm run bootstrap -- --scope=mobile
```

--------------------------------

### Run web clipper

Source: https://github.com/streetwriters/notesnook/blob/master/extensions/web-clipper/README.md

Start the development build of the web clipper for Chrome.

```sh
npm run dev:chrome
```

--------------------------------

### Run Webapp for Desktop

Source: https://github.com/streetwriters/notesnook/blob/master/apps/desktop/README.md

Start the web application specifically for the desktop environment.

```bash
cd apps/web
npm run start:desktop
```

--------------------------------

### Launch Desktop App

Source: https://github.com/streetwriters/notesnook/blob/master/apps/desktop/README.md

Start the desktop application from the project root in a separate terminal.

```bash
npm run start:desktop
```

--------------------------------

### Useful Development Commands

Source: https://github.com/streetwriters/notesnook/blob/master/apps/mobile/README.md

Commands to start the Metro bundler or the Re.Pack bundler independently for development purposes.

```bash
# start Metro only
npm run start:metro

# start Re.Pack bundler
npm run start:repack
```

--------------------------------

### Prepare and Run Notesnook App on iOS

Source: https://github.com/streetwriters/notesnook/blob/master/apps/mobile/README.md

Install CocoaPods dependencies and then run the Notesnook application on an iOS simulator or physical device. This process may take a while.

```bash
# this might take a while to complete
npm run prepare:ios

npm run start:ios
```

--------------------------------

### Build and Run iOS E2E Tests

Source: https://github.com/streetwriters/notesnook/blob/master/apps/mobile/README.md

Build and execute end-to-end tests for the iOS version of the app using Detox. If simulator tooling is missing, install AppleSimulatorUtils via Homebrew.

```bash
npm run build:ios
npm run test:ios
```

```bash
brew tap wix/brew
brew install applesimutils
```

--------------------------------

### Run Notesnook App on Android

Source: https://github.com/streetwriters/notesnook/blob/master/apps/mobile/README.md

Start the Notesnook application on an Android emulator or physical device. Ensure an Android emulator is set up or a physical device with USB debugging enabled is connected.

```bash
npm run start:android
```

--------------------------------

### Clone Notesnook Monorepo

Source: https://github.com/streetwriters/notesnook/blob/master/apps/mobile/README.md

Clone the Notesnook monorepo and navigate into the project directory. Ensure you have Git installed.

```bash
git clone https://github.com/streetwriters/notesnook.git

# change directory
cd notesnook
```

--------------------------------

### Get Current Theme Colors in React

Source: https://context7.com/streetwriters/notesnook/llms.txt

Use the `useThemeColors` hook to access theme colors within a React component. Specify the scope (e.g., 'base', 'editor') to get relevant color palettes.

```typescript
import {
  useThemeColors,
  useThemeEngineStore,
  ThemeLight,
  ThemeDark,
  validateTheme,
  themeToCSS
} from "@notesnook/theme";

// Get current theme colors in React component
function MyComponent() {
  const { colors, isDark, scope } = useThemeColors("base");

  return (
    <div style={{
      backgroundColor: colors.primary.background,
      color: colors.primary.paragraph
    }}>
      Theme is {isDark ? "dark" : "light"}
    </div>
  );
}
```

--------------------------------

### Example DCO commit message

Source: https://github.com/streetwriters/notesnook/blob/master/CONTRIBUTING.md

The required format for the Signed-off-by line in commit messages.

```text
Signed-off-by: Jane Smith <jane.smith@email.com>
```

--------------------------------

### Example commit messages with scopes

Source: https://github.com/streetwriters/notesnook/blob/master/CONTRIBUTING.md

Commits must include a valid scope prefixing the subject line. Scopes indicate the area of the project affected by the changes.

```text
docs: list all valid scopes in commit guidelines
```

```text
web: impl xyz feature
```

```text
crypto: update libsodium version
```

--------------------------------

### Build and serve production

Source: https://github.com/streetwriters/notesnook/blob/master/apps/web/README.md

Compile the application for production and serve the build files locally.

```bash
npm run build:web

# serve the app locally
npx serve apps/web/build
```

--------------------------------

### Build and serve production

Source: https://github.com/streetwriters/notesnook/blob/master/apps/theme-builder/README.md

Compiles the application for production and serves it locally.

```bash
npm run build:theme-builder

# serve the app locally
npx serve apps/theme-builder/build
```

--------------------------------

### Initialize Application Theme

Source: https://github.com/streetwriters/notesnook/blob/master/apps/theme-builder/src/index.html

Applies the stored color scheme and theme CSS to the document root on initialization.

```javascript
import { themeToCSS } from "@notesnook/theme"; const colorScheme = JSON.parse( window.localStorage.getItem("colorScheme") || '"light"' ); const root = document.querySelector("html"); if (root) root.setAttribute("data-theme", colorScheme); const theme = window.localStorage.getItem(`theme:${colorScheme}`); if (theme) { const css = themeToCSS(JSON.parse(theme)); const stylesheet = document.getElementById("theme-colors"); if (stylesheet) stylesheet.innerHTML = css; }
```

--------------------------------

### Initialize and Use Logger

Source: https://context7.com/streetwriters/notesnook/llms.txt

Demonstrates creating a logger instance with a console reporter, logging messages at different levels, creating scoped loggers, and measuring performance. Ensure the reporter is correctly configured.

```typescript
import { Logger, NoopLogger, combineReporters, consoleReporter } from "@notesnook/logger";

// Create logger with console reporter
const logger = new Logger({
  reporter: consoleReporter,
  lastTime: Date.now()
});

// Log at different levels
logger.info("Application started");
logger.debug("Debug information", { userId: "123" });
logger.warn("Warning message");
logger.error(new Error("Something went wrong"), "Operation failed");
logger.fatal(new Error("Critical failure"), "System crash");

// Create scoped logger
const dbLogger = logger.scope("database");
dbLogger.info("Database connected");  // Logs: [database] Database connected

// Measure performance
logger.measure("database-query");
// ... perform operation ...
logger.measure("database-query");  // Logs: database-query took 150.25ms

// Combine multiple reporters
const combinedReporter = combineReporters([
  consoleReporter,
  customFileReporter,
  customNetworkReporter
]);

const multiLogger = new Logger({
  reporter: combinedReporter,
  lastTime: Date.now()
});

// NoopLogger for testing or disabling logs
const noop = new NoopLogger();
noop.info("This won't be logged");
```

--------------------------------

### Build Production Packages

Source: https://github.com/streetwriters/notesnook/blob/master/apps/desktop/README.md

Commands to create final production packages for different operating systems.

```bash
npm run release -- --rebuild

# For macOS
npx electron-builder --config=electron-builder.config.js --mac dmg --arm64 --x64 --publish never

# For Linux (AppImage)
npx electron-builder --config=electron-builder.config.js --linux AppImage:x64 AppImage:arm64 --publish never

# For Windows
npx electron-builder --config=electron-builder.config.js --win --publish never
```

--------------------------------

### Initialize Rich Text Editor with Options

Source: https://context7.com/streetwriters/notesnook/llms.txt

Initialize the Tiptap-based editor using the `useTiptap` hook. Configure placeholders, date/time formats, and callbacks for various editor functionalities.

```typescript
import { useTiptap, Toolbar, getHTMLFromFragment } from "@notesnook/editor";

function NoteEditor() {
  const editor = useTiptap({
    placeholder: "Start writing your note...",

    // Date/time formatting
    dateFormat: "MM/DD/YYYY",
    timeFormat: "12-hour",
    dayFormat: "short",

    // Callbacks
    openLink: (url, newTab) => window.open(url, newTab ? "_blank" : "_self"),

    downloadAttachment: async (attachment) => {
      const data = await fetchAttachment(attachment.hash);
      downloadFile(data, attachment.filename);
    },

    openAttachmentPicker: (type) => {
      // "image" | "file" | "camera"
      showFilePicker(type);
    },

    previewAttachment: (attachment) => {
      showPreviewModal(attachment);
    },

    getAttachmentData: async (attachment) => {
      return await db.attachments.getData(attachment.hash);
    },

    createInternalLink: async (attributes) => {
      const selectedNote = await showNotePicker();
      return {
        href: `nn://note/${selectedNote.id}`,
        title: selectedNote.title
      };
    },

    copyToClipboard: (text, html) => {
      navigator.clipboard.write([
        new ClipboardItem({
          "text/plain": new Blob([text], { type: "text/plain" }),
          "text/html": new Blob([html || text], { type: "text/html" })
        })
      ]);
    },

    // Editor options
    isMobile: false,
    doubleSpacedLines: true,
    enableFontLigatures: true,

    // Initial content
    content: "<p>Initial content here</p>"
  });

  return (
    <div>
      <Toolbar editor={editor} />
      <EditorContent editor={editor} />
    </div>
  );
}

// Get HTML from editor
const html = editor.getHTML();

// Get plain text
const text = editor.getText();

// Set content
editor.commands.setContent("<p>New content</p>");

// Insert at cursor
editor.commands.insertContent("<strong>Bold text</strong>");

// Toggle formatting
editor.chain().focus().toggleBold().run();
editor.chain().focus().toggleItalic().run();
editor.chain().focus().toggleHeading({ level: 2 }).run();

// Insert special elements
editor.chain().focus().insertTable({ rows: 3, cols: 3 }).run();
editor.chain().focus().setCodeBlock({ language: "javascript" }).run();
editor.chain().focus().setTaskList().run();
```

--------------------------------

### Run in Release Mode

Source: https://github.com/streetwriters/notesnook/blob/master/apps/desktop/README.md

Compile and run the application in production mode without generating packages.

```bash
npm run staging -- --rebuild
```

--------------------------------

### Initialize the Notesnook Database

Source: https://context7.com/streetwriters/notesnook/llms.txt

Configures the Database instance with storage, file system, and SQLite options before initialization.

```typescript
import Database from "@notesnook/core";
import { SqliteDialect } from "@streetwriters/kysely";
import BetterSQLite3 from "better-sqlite3-multiple-ciphers";

// Create and configure the database instance
const db = new Database();

db.setup({
  storage: new NodeStorageInterface(),  // Platform-specific storage implementation
  eventsource: EventSource,              // For real-time sync updates
  fs: new FileStorage(),                 // File system for attachments
  compressor: async () => Compressor,    // Compression for backups
  maxNoteVersions: async () => 1000,     // Note history limit
  sqliteOptions: {
    dialect: (name) => new SqliteDialect({
      database: BetterSQLite3(":memory:").unsafeMode(true)
    }),
    password: "optional-encryption-password"
  },
  batchSize: 500
});

// Initialize the database (creates tables, runs migrations)
await db.init();

console.log("Database initialized:", db.isInitialized);
// Output: Database initialized: true
```

--------------------------------

### Define Application Styles

Source: https://github.com/streetwriters/notesnook/blob/master/apps/theme-builder/src/index.html

CSS rules for splash screen, skeleton loaders, and layout responsiveness.

```css
#splash { display: none !important; } html { overscroll-behavior: none; } html[data-theme="light"] .react-loading-skeleton { --base-color: var(--background-secondary); --highlight-color: #var(--background-secondary); } html[data-theme="dark"] .react-loading-skeleton { --base-color: var(--background-secondary); --highlight-color: var(--background-secondary); } #splash { background-color: var(--background); height: 100%; width: 100%; position: absolute; top: 0; left: 0; display: flex; flex-direction: column; justify-content: center; align-items: center; } #splash svg { transform: scale(1); animation: pulse 2s infinite; } @keyframes pulse { 0% { transform: scale(0.9); } 70% { transform: scale(1); } 100% { transform: scale(0.9); } } html, body { font-size: 16px; } @media only screen and (max-width: 480px) { html, body { font-size: 18px; background-color: var(--background); } } :root, body, #root { margin: 0 !important; height: 100%; overflow: hidden; } #root { display: flex; flex-direction: column; } /* svg { width: 1.5rem; } */ .ReactModal__Overlay { opacity: 0; transition: opacity 200ms ease-in-out; } .ReactModal__Overlay--after-open { opacity: 1; } .ReactModal__Overlay--before-close { opacity: 0; } .slide { background-color: transparent !important; } .carousel.carousel-slider { display: flex; flex-direction: row; }
```

--------------------------------

### Switch iOS Build Configuration

Source: https://github.com/streetwriters/notesnook/blob/master/apps/mobile/ios/build-configs/README.md

Execute this script from the 'apps/mobile' directory to set the active build configuration to 'production' or 'staging'.

```bash
bash ios/build-configs/use-ios-build-config.sh production
```

```bash
bash ios/build-configs/use-ios-build-config.sh staging
```

--------------------------------

### Navigate to web clipper directory

Source: https://github.com/streetwriters/notesnook/blob/master/extensions/web-clipper/README.md

Change the working directory to the web clipper folder.

```sh
cd extensions/web-clipper
```

--------------------------------

### Build iOS App with Specific Config

Source: https://github.com/streetwriters/notesnook/blob/master/apps/mobile/ios/build-configs/README.md

Compile the iOS application directly using a specific configuration file, such as 'ios-build.staging.xcconfig'.

```bash
xcodebuild \
  -workspace ios/Notesnook.xcworkspace \
  -scheme Notesnook \
  -configuration Release \
  -xcconfig ios/build-configs/ios-build.staging.xcconfig
```

--------------------------------

### Android Release Commands

Source: https://github.com/streetwriters/notesnook/blob/master/apps/mobile/README.md

Helper commands for generating release builds of the Notesnook Android application.

```bash
npm run release:android
npm run release:android:bundle
```

--------------------------------

### Build iOS App with Active Config

Source: https://github.com/streetwriters/notesnook/blob/master/apps/mobile/ios/build-configs/README.md

Use xcodebuild to compile the iOS application, referencing the active configuration file. Ensure you are in the 'apps/mobile' directory.

```bash
xcodebuild \
  -workspace ios/Notesnook.xcworkspace \
  -scheme Notesnook \
  -configuration Release \
  -xcconfig ios/build-configs/ios-build.active.xcconfig
```

--------------------------------

### Application CSS Styles

Source: https://github.com/streetwriters/notesnook/blob/master/apps/web/src/index.html

Global CSS styles for themes, splash screen animations, and layout constraints.

```css
html { overscroll-behavior: none; } html[data-theme="light"] .react-loading-skeleton { --base-color: var(--background-secondary); --highlight-color: #var(--background-secondary); } html[data-theme="dark"] .react-loading-skeleton { --base-color: var(--background-secondary); --highlight-color: var(--background-secondary); } #splash { background-color: var(--background); height: 100%; width: 100%; position: absolute; top: 0; left: 0; display: flex; flex-direction: column; justify-content: center; align-items: center; } #splash svg { transform: scale(1); animation: pulse 2s infinite; } @keyframes pulse { 0% { transform: scale(0.9); } 70% { transform: scale(1); } 100% { transform: scale(0.9); } } html, body { font-size: 16px; } @media only screen and (max-width: 480px) { html, body { font-size: 18px; background-color: var(--background); } } :root, body, #root { margin: 0 !important; height: 100%; overflow: hidden; } #root { display: flex; flex-direction: column; } /* svg { width: 1.5rem; } */ .ReactModal__Overlay { opacity: 0; transition: opacity 200ms ease-in-out; } .ReactModal__Overlay--after-open { opacity: 1; } .ReactModal__Overlay--before-close { opacity: 0; } .slide { background-color: transparent !important; } .carousel.carousel-slider { display: flex; flex-direction: row; }
```

--------------------------------

### Run tests

Source: https://github.com/streetwriters/notesnook/blob/master/apps/web/README.md

Execute the end-to-end test suite using Playwright.

```bash
npm run test:web
```

--------------------------------

### Build and Run Android E2E Tests

Source: https://github.com/streetwriters/notesnook/blob/master/apps/mobile/README.md

Build and execute end-to-end tests for the Android version of the app using Detox. Includes commands for both release and debug configurations.

```bash
npm run build:android
npm run test:android
```

```bash
npm run build:android:debug
npm run start:metro
npm run test:android:debug
```

--------------------------------

### Manage Notebooks and Notes

Source: https://context7.com/streetwriters/notesnook/llms.txt

Create, link, and query notebooks and sub-notebooks. Assign notes to notebooks and manage their hierarchy. Supports operations like pinning, deleting, and retrieving counts.

```typescript
// Create a notebook
const notebookId = await db.notebooks.add({
  title: "Work Projects",
  description: "All my work-related notes"
});
```

```typescript
// Create a sub-notebook
const subNotebookId = await db.notebooks.add({
  title: "Q1 2024 Projects"
});
```

```typescript
// Link sub-notebook to parent notebook
await db.relations.add(
  { type: "notebook", id: notebookId },
  { type: "notebook", id: subNotebookId }
);
```

```typescript
// Add note to notebook
await db.notes.addToNotebook(subNotebookId, noteId);
```

```typescript
// Get all root notebooks (no parent)
const rootNotebooks = await db.notebooks.roots.items();
```

```typescript
// Get all notebooks
const allNotebooks = await db.notebooks.all.items();
```

```typescript
// Get notebook by ID
const notebook = await db.notebooks.notebook(notebookId);
console.log(notebook?.title);  // Output: "Work Projects"
```

```typescript
// Find notebook by title
const foundNotebook = await db.notebooks.find("Work Projects");
```

```typescript
// Get breadcrumbs for navigation
const breadcrumbs = await db.notebooks.breadcrumbs(subNotebookId);
// Output: [{ id: "...", title: "Work Projects" }, { id: "...", title: "Q1 2024 Projects" }]
```

```typescript
// Get total notes count in notebook (including sub-notebooks)
const [totalNotes] = await db.notebooks.totalNotes(notebookId);
```

```typescript
// Get all note IDs in notebook hierarchy
const noteIds = await db.notebooks.notes(notebookId);
```

```typescript
// Remove note from notebook
await db.notes.removeFromNotebook(notebookId, noteId);
```

```typescript
// Pin notebook
await db.notebooks.pin(true, notebookId);
```

```typescript
// Delete notebook (moves to trash)
await db.notebooks.moveToTrash(notebookId);
```

--------------------------------

### Run Prettier code formatter

Source: https://github.com/streetwriters/notesnook/blob/master/CONTRIBUTING.md

Format your code using Prettier to ensure consistent style. Run this command after making code changes.

```bash
npm run prettier
```

--------------------------------

### Run core tests

Source: https://github.com/streetwriters/notesnook/blob/master/packages/core/README.md

Execute the Jest test suite to verify the core functionality.

```bash
npm run test:core
```

--------------------------------

### Run ESLint linter

Source: https://github.com/streetwriters/notesnook/blob/master/CONTRIBUTING.md

Check your code for styling issues using ESLint. This command helps catch most style problems.

```bash
npm run lint
```

--------------------------------

### Create and Process Backups

Source: https://context7.com/streetwriters/notesnook/llms.txt

Generate encrypted or unencrypted backups of your data using `db.backup.export()`. The export function returns a generator for handling backup chunks, including files and attachments. Use `db.backup.import()` to restore data.

```typescript
// Create backup (generator for chunked output)
const backupGenerator = db.backup.export({
  type: "web",        // "web" | "mobile" | "node"
  encrypt: true,      // Encrypt backup with user key
  mode: "full"        // "full" | "partial"
});

// Process backup chunks
for await (const chunk of backupGenerator) {
  if (chunk.type === "file") {
    // Save backup file
    console.log(`Backup chunk: ${chunk.path}`);
    await saveFile(chunk.path, chunk.data);
  } else if (chunk.type === "attachment") {
    // Handle attachment export
    console.log(`Attachment ${chunk.current}/${chunk.total}: ${chunk.hash}`);
  }
}

// Get last backup time
const lastBackupTime = await db.backup.lastBackupTime();

// Restore from backup
const backupFile = JSON.parse(backupFileContent);
await db.backup.import(backupFile, "user-password");
```

--------------------------------

### Manage Notes Collection

Source: https://context7.com/streetwriters/notesnook/llms.txt

Demonstrates creating, updating, retrieving, organizing, and deleting notes within the Notesnook database.

```typescript
// Add a new note with content
const noteId = await db.notes.add({
  title: "My First Note",
  content: {
    type: "tiptap",
    data: "<p>Hello, this is my encrypted note content!</p>"
  }
});

// Retrieve the note
const note = await db.notes.note(noteId);
console.log(note?.title);  // Output: "My First Note"

// Get note content
const content = await db.content.get(note.contentId);
console.log(content?.data);  // Output: "<p>Hello, this is my encrypted note content!</p>"

// Update note properties
await db.notes.add({
  id: noteId,
  title: "Updated Title",
  content: {
    type: "tiptap",
    data: "<p>Updated content with <strong>bold text</strong></p>"
  }
});

// Pin, favorite, and archive notes
await db.notes.pin(true, noteId);
await db.notes.favorite(true, noteId);
await db.notes.archive(true, noteId);

// Get all notes with filtering
const allNotes = await db.notes.all.items();
const pinnedNotes = await db.notes.pinned.items();
const favoriteNotes = await db.notes.favorites.items();
const archivedNotes = await db.notes.archived.items();

// Export note to different formats
const htmlExport = await db.notes.export(noteId, { format: "html" });
const markdownExport = await db.notes.export(noteId, { format: "md" });
const textExport = await db.notes.export(noteId, { format: "txt" });

// Delete note (move to trash)
await db.notes.moveToTrash(noteId);

// Permanently delete note
await db.notes.remove(noteId);
```

--------------------------------

### StreamableFS File Operations

Source: https://context7.com/streetwriters/notesnook/llms.txt

Shows how to use StreamableFS for creating, writing, reading, and deleting files in IndexedDB using a streaming interface. Supports chunked operations and provides methods for checking existence, listing, moving, and clearing files.

```typescript
import { StreamableFS } from "@notesnook/streamable-fs";

// Create instance with storage backend
const fs = new StreamableFS(indexedDBStorage);

// Create a new file
const fileHandle = await fs.createFile(
  "document.pdf",
  1024000,              // size in bytes
  "application/pdf",
  { overwrite: true }
);

// Write data in chunks
const writer = fileHandle.writeable;
await writer.write(chunk1);
await writer.write(chunk2);
await writer.close();

// Read file
const readHandle = await fs.readFile("document.pdf");
if (readHandle) {
  // Get readable stream
  const reader = readHandle.readable;

  // Or read as blob
  const blob = await readHandle.toBlob();

  // Get file info
  console.log(readHandle.file);
  // Output: { filename: "document.pdf", size: 1024000, type: "application/pdf" }
}

// Check if file exists
const exists = await fs.exists("document.pdf");

// List all files
const files = await fs.list();

// Delete file
await fs.deleteFile("document.pdf");

// Bulk delete files
await fs.bulkDeleteFiles(["file1.pdf", "file2.pdf"]);

// Move file
const sourceHandle = await fs.readFile("source.pdf");
const destHandle = await fs.createFile("dest.pdf", sourceHandle.file.size, sourceHandle.file.type);
await fs.moveFile(sourceHandle, destHandle);

// Clear all files
await fs.clear();
```

--------------------------------

### User Authentication and Management

Source: https://context7.com/streetwriters/notesnook/llms.txt

The UserManager handles user registration, login, and session management. Supports email-based authentication and multi-factor authentication (MFA). Use `signup`, `authenticateEmail`, `authenticatePassword`, and `authenticateMultiFactorCode` for user flows.

```typescript
// Sign up new user
await db.user.signup("user@example.com", "secure-password");

// Login flow - Step 1: Authenticate email
const mfaInfo = await db.user.authenticateEmail("user@example.com");

// Login flow - Step 2: Handle MFA if required
if (mfaInfo?.mfa) {
  await db.user.authenticateMultiFactorCode("123456", "totp");
}

// Login flow - Step 3: Authenticate with password
await db.user.authenticatePassword(
  "user@example.com",
  "secure-password",
  "hashed-password"
);
```

```typescript
// Get current user
const user = await db.user.getUser();
console.log(user?.email);

// Fetch latest user data from server
const freshUser = await db.user.fetchUser();

// Check if user is logged in
const isLoggedIn = await db.user.isLoggedIn();

// Logout
await db.user.logout(false, "User requested logout");

// Delete account
await db.user.deleteUser("secure-password");
```

--------------------------------

### Manage Tags and Colors

Source: https://context7.com/streetwriters/notesnook/llms.txt

Organize notes using text-based tags and visual color categorization. These are managed through the relations system and can be added to or removed from notes.

```typescript
// Create a tag
const tagId = await db.tags.add({ title: "important" });
```

```typescript
// Add tag to note
await db.relations.add(
  { type: "tag", id: tagId },
  { type: "note", id: noteId }
);
```

```typescript
// Get all tags
const allTags = await db.tags.all.items();
```

```typescript
// Get tags for a specific note
const noteTags = await db.notes.tags(noteId);
```

```typescript
// Create a color
const colorId = await db.colors.add({
  title: "Red",
  colorCode: "#ff0000"
});
```

```typescript
// Add color to note
await db.relations.add(
  { type: "color", id: colorId },
  { type: "note", id: noteId }
);
```

```typescript
// Get all colors
const allColors = await db.colors.all.items();
```

```typescript
// Default colors are provided
import { DefaultColors } from "@notesnook/core";
console.log(DefaultColors);
// Output: ["red", "orange", "yellow", "green", "blue", "purple", "gray"]
```

```typescript
// Remove tag from note
await db.relations.unlink(
  { type: "tag", id: tagId },
  { type: "note", id: noteId }
);
```

--------------------------------

### Hashing and Key Pair Generation with NNCrypto

Source: https://context7.com/streetwriters/notesnook/llms.txt

NNCrypto provides utilities for password hashing using Argon2 and generating key pairs for asymmetric encryption. Use `hash` for secure password storage and `deriveKeyPair`/`exportKeyPair` for cryptographic key management.

```typescript
// Hash password
const hashedPassword = await crypto.hash("password", "salt");

// Generate key pair for asymmetric encryption
const keyPair = await crypto.deriveKeyPair();
const serializedKeyPair = await crypto.exportKeyPair();
```

--------------------------------

### Configure Custom API Hosts

Source: https://context7.com/streetwriters/notesnook/llms.txt

Customize API endpoints for authentication, main API, server-sent events, and subscriptions using the `db.host()` method. This is useful for directing traffic to specific server instances or development environments.

```typescript
// Set custom API hosts
db.host({
  AUTH_HOST: "https://auth.example.com",
  API_HOST: "https://api.example.com",
  SSE_HOST: "https://sse.example.com",
  SUBSCRIPTIONS_HOST: "https://subscriptions.example.com"
});
```

--------------------------------

### Set Theme Programmatically

Source: https://context7.com/streetwriters/notesnook/llms.txt

Access the theme engine store to programmatically set the application's theme. Ensure the theme object (e.g., `ThemeDark`) is imported.

```typescript
// Set theme programmatically
const { setTheme } = useThemeEngineStore.getState();
setTheme(ThemeDark);
```

--------------------------------

### Streaming Encryption and Decryption with NNCrypto

Source: https://context7.com/streetwriters/notesnook/llms.txt

For large files, use NNCrypto's streaming capabilities. Create `createEncryptionStream` or `createDecryptionStream` to process data in chunks, which is more memory-efficient than loading entire files.

```typescript
// Create encryption stream for large files
const encryptionStream = await crypto.createEncryptionStream(serializedKey);

// Create decryption stream
const decryptionStream = await crypto.createDecryptionStream(
  serializedKey,
  cipher.iv
);
```

--------------------------------

### Handle Editor Input Event

Source: https://github.com/streetwriters/notesnook/blob/master/apps/mobile/ios/extension.bundle/plaineditor.html

Listens for input events on the editor element and posts the updated HTML content. This is crucial for real-time updates of the note's content.

```javascript
document.getElementById("editor").addEventListener("input", function (event) {
  postMessage('content', event.target.innerHTML);
}, false);
```

--------------------------------

### Data Synchronization Operations

Source: https://context7.com/streetwriters/notesnook/llms.txt

The sync system enables bidirectional data synchronization across devices. Supports 'full', 'fetch', and 'send' modes. Use `db.sync()` for synchronization and `db.hasUnsyncedChanges()` to check status.

```typescript
// Perform full sync
await db.sync({ type: "full" });

// Fetch changes from server only
await db.sync({ type: "fetch" });

// Send local changes to server only
await db.sync({ type: "send" });

// Force sync even if already synced
await db.sync({ type: "full", force: true });

// Check for unsynced changes
const hasChanges = await db.hasUnsyncedChanges();

// Get last sync timestamp
const lastSynced = await db.lastSynced();
console.log(new Date(lastSynced));
```

--------------------------------

### Encrypt and Decrypt Data with NNCrypto

Source: https://context7.com/streetwriters/notesnook/llms.txt

Use NNCrypto for end-to-end encryption. Derive keys from passwords, encrypt/decrypt strings or binary data, and handle multiple items efficiently. Ensure correct input/output formats (e.g., 'text', 'base64').

```typescript
import { NNCrypto } from "@notesnook/crypto";

const crypto = new NNCrypto();

// Derive encryption key from password
const encryptionKey = await crypto.deriveKey("user-password", "salt-value");

// Export key for storage
const serializedKey = await crypto.exportKey("user-password", "salt-value");
// Output: { key: "...", salt: "..." }

// Encrypt data
const cipher = await crypto.encrypt(
  serializedKey,
  "Secret message to encrypt",
  "text",      // input format
  "base64"     // output format
);
// Output: { cipher: "...", iv: "...", salt: "...", ... }

// Decrypt data
const decrypted = await crypto.decrypt(
  serializedKey,
  cipher,
  "text"       // output format
);
console.log(decrypted);  // Output: "Secret message to encrypt"
```

```typescript
// Encrypt multiple items at once
const ciphers = await crypto.encryptMulti(
  serializedKey,
  ["message1", "message2", "message3"],
  "text",
  "base64"
);

// Decrypt multiple items
const decryptedItems = await crypto.decryptMulti(
  serializedKey,
  ciphers,
  "text"
);
```

--------------------------------

### Validate and Set Custom Theme

Source: https://context7.com/streetwriters/notesnook/llms.txt

Validate a custom theme object using `validateTheme` before applying it. Handle validation errors by logging them to the console.

```typescript
// Validate custom theme
const customTheme = {
  name: "My Custom Theme",
  id: "my-custom-theme",
  version: 1,
  compatibilityVersion: 1,
  colorScheme: "dark",
  // ... theme definition
};

const validationResult = validateTheme(customTheme);
if (validationResult.success) {
  setTheme(customTheme);
} else {
  console.error("Invalid theme:", validationResult.errors);
}
```

--------------------------------

### Sign commit with DCO

Source: https://github.com/streetwriters/notesnook/blob/master/CONTRIBUTING.md

Append the DCO sign-off to your commit message. Ensure your git user.name and user.email are configured.

```bash
git commit -s -m "feat: add new feature"
```

--------------------------------

### Convert Theme to CSS Variables

Source: https://context7.com/streetwriters/notesnook/llms.txt

Convert a theme object into a string of CSS variables using `themeToCSS`. This is useful for applying themes directly in CSS.

```typescript
// Convert theme to CSS variables
const cssVariables = themeToCSS(customTheme);
// Output: ":root { --nn-primary-background: #1a1a1a; ... }"
```

--------------------------------

### Use Scoped Themes for UI Areas

Source: https://context7.com/streetwriters/notesnook/llms.txt

Apply different theme scopes to specific UI components like editors or navigation menus by passing the scope name to `useThemeColors`.

```typescript
// Use scoped themes for different UI areas
function EditorArea() {
  const { colors } = useThemeColors("editor");
  // Uses editor-specific colors
}

function Sidebar() {
  const { colors } = useThemeColors("navigationMenu");
  // Uses navigation menu colors
}
```

--------------------------------

### Web Clipper Page Clipping

Source: https://context7.com/streetwriters/notesnook/llms.txt

Provides functions to clip web pages, articles, screenshots, and allows manual element selection. Options include clipping full pages with styles, only visible content, or extracting article content using Readability. CORS proxy configuration is supported.

```typescript
import { clipPage, clipArticle, clipScreenshot, enterNodeSelectionMode } from "@notesnook/clipper";

// Clip entire page with styles
const pageHtml = await clipPage(document, false, {
  styles: true,
  images: true,
  inlineImages: true,
  corsProxy: "https://cors-proxy.example.com"
});
// Output: "<!doctype html><html>...</html>"

// Clip only visible content
const visibleHtml = await clipPage(document, true, { styles: true });

// Clip article content (extracts main content using Readability)
const articleHtml = await clipArticle(document, {
  styles: true,
  images: true
});
// Output: Cleaned article HTML without navigation, ads, etc.

// Take screenshot
const screenshotHtml = await clipScreenshot(
  document.body,   // target element (optional)
  "jpeg",          // "jpeg" | "png" | "svg" | "raw"
  { corsProxy: "https://cors-proxy.example.com" }
);
// Output: <img src="data:image/jpeg;base64,..." />

// Enter manual selection mode (for browser extension)
const selectedHtml = await enterNodeSelectionMode(document, {
  styles: true,
  images: true
});
// User clicks elements to select, then clicks "Clip" button
// Output: HTML of selected elements
```

--------------------------------

### Post Message to React Native WebView

Source: https://github.com/streetwriters/notesnook/blob/master/apps/mobile/ios/extension.bundle/plaineditor.html

Sends messages to a React Native WebView. Ensure the WebView is available via `window.ReactNativeWebView` before calling.

```javascript
function postMessage(type, value) {
  if (window.ReactNativeWebView) {
    window.ReactNativeWebView.postMessage(
      JSON.stringify({
        type: type,
        value: value
      })
    );
  }
}
```

--------------------------------

### Attach Message Listener for Editor Communication

Source: https://github.com/streetwriters/notesnook/blob/master/apps/mobile/ios/extension.bundle/plaineditor.html

Attaches a message event listener to the window or document, depending on the browser (Safari uses window). It parses incoming JSON messages to update the editor's HTML, theme, line spacing, or focus.

```javascript
let styleElementDocument;
let doubleSpacedLines = true;

function attachOnMessage() {
  let isSafari = navigator.vendor.match(/apple/i);
  let listenerHandler = document;
  if (isSafari) {
    listenerHandler = window;
  }
  listenerHandler.addEventListener('message', function (data) {
    console.log("message", data);
    let message = JSON.parse(data.data);
    let type = message.type;
    let value = message.value;
    switch (type) {
      case 'html':
        document.getElementById('editor').innerHTML = value;
        break;
      case 'theme':
        if (!styleElementDocument) {
          styleElementDocument = document.createElement('style');
          styleElementDocument.type = 'text/css';
          styleElementDocument.innerHTML = value;
          document.getElementsByTagName('head')[0].appendChild(styleElementDocument);
        } else {
          styleElementDocument.innerHTML = node;
        }
        break;
      case 'line-spacing': {
        doubleSpacedLines = JSON.parse(value);
      }
      case 'focus':
        document.getElementById('editor').focus();
        break;
      default:
        break;
    }
  });
}
```

--------------------------------

### Manage Vault Encryption

Source: https://context7.com/streetwriters/notesnook/llms.txt

Encrypt sensitive notes using the Vault feature. Requires a password for creation, unlocking, and modification. Supports locking, unlocking, temporary opening, saving changes, and password management.

```typescript
// Create vault with password
await db.vault.create("my-secure-password");
```

```typescript
// Check if vault exists
const vaultExists = await db.vault.exists();
```

```typescript
// Lock a note (add to vault)
await db.vault.add(noteId);
```

```typescript
// Unlock vault to access locked notes
await db.vault.unlock("my-secure-password");
```

```typescript
// Open a locked note temporarily
const unlockedNote = await db.vault.open(noteId, "my-secure-password");
console.log(unlockedNote?.content);
```

```typescript
// Save changes to a locked note
await db.vault.save({
  id: noteId,
  content: {
    type: "tiptap",
    data: "<p>Updated secret content</p>"
  },
  sessionId: "session-123"
});
```

```typescript
// Permanently unlock a note (remove from vault)
await db.vault.remove(noteId, "my-secure-password");
```

```typescript
// Change vault password
await db.vault.changePassword("old-password", "new-password");
```

```typescript
// Lock the vault
await db.vault.lock();
```

```typescript
// Check if vault is unlocked
console.log(db.vault.unlocked);  // Output: false
```

```typescript
// Clear vault (unlock all notes)
await db.vault.clear("my-secure-password");
```

```typescript
// Delete vault entirely
await db.vault.delete(false);  // false = keep notes, true = delete all locked notes
```

--------------------------------

### Validate Service Worker Track

Source: https://github.com/streetwriters/notesnook/blob/master/apps/web/src/index.html

Validates the service worker cache based on the release track cookie and unregisters mismatched workers.

```javascript
(async function validateServiceWorkerTrack() { const cookie = document.cookie.match(/release\-track=([^;]+)/); const releaseTrack = cookie ? cookie[1] : "stable"; const expectedPrefix = releaseTrack === "beta" ? "notesnook-beta" : "notesnook"; const cacheKeys = await caches.keys(); const mismatched = cacheKeys.some( (key) => !key.startsWith(expectedPrefix) ); if (mismatched) { const regs = await navigator.serviceWorker.getRegistrations(); await Promise.all(regs.map((r) => r.unregister())); await Promise.all(cacheKeys.map((key) => caches.delete(key))); window.location.reload(); } })();
```
Tokens:
Raw