Codakey
Play
← Back to notesnook

How to Deploy & Use notesnook

Notesnook Deployment & Usage Guide

1. Prerequisites

Runtime & Tools

  • Node.js (v16 or higher recommended)
  • npm (v7 or higher) - Notesnook explicitly uses npm, not Yarn or PNPM
  • Git for cloning the repository
  • For mobile development:
    • Android Studio (for Android builds)
    • Xcode (for iOS builds, macOS only)
  • For desktop development:
    • Electron build dependencies for your platform

Accounts & Services

  • Email account for Notesnook registration (required for sync and encryption key management)
  • Optional: Apple Developer Account (iOS deployment)
  • Optional: Google Play Developer Account (Android deployment)

2. Installation

Clone the Repository

git clone https://github.com/streetwriters/notesnook.git
cd notesnook

Install Dependencies

Notesnook uses a monorepo structure with npm workspaces. Install all dependencies with:

npm install

This will install dependencies for all packages and apps in the monorepo:

  • Web client (@notesnook/web)
  • Desktop client (@notesnook/desktop)
  • Mobile clients (@notesnook/mobile)
  • Core packages (@notesnook/core, @notesnook/crypto, @notesnook/editor, etc.)

Platform-Specific Setup

For Mobile Development (Android/iOS):

cd apps/mobile
npm run setup:android  # For Android
# OR
npm run setup:ios      # For iOS (macOS only)

For Desktop Development:

cd apps/desktop
# No additional setup required beyond npm install

3. Configuration

Environment Variables

Notesnook uses end-to-end encryption with XChaCha20-Poly1305 and Argon2. Most configuration is handled internally, but you may need:

Web/Desktop Configuration

Create a .env file in apps/web or apps/desktop:

# Optional: Custom API endpoint (defaults to https://api.notesnook.com)
REACT_APP_API_URL=https://your-api-endpoint.com

# Optional: Enable debug logging
DEBUG=true

Mobile Configuration

For mobile, configuration is managed through:

  • apps/mobile/app/services/settings.ts - Application settings
  • apps/mobile/app/common/database - Database configuration using SQLite with IndexedDB VFS

Database Configuration

Notesnook uses SQLite with WebAssembly support:

  • Web/Desktop: Uses IndexedDB-based virtual file system (IndexedDbVFS)
  • Mobile: Uses React Native SQLite storage
  • Encryption: All data is encrypted client-side before storage

API Keys

No external API keys are required for basic functionality. The encryption happens locally using:

  • @notesnook/sodium - libsodium wrapper for cryptography
  • @notesnook/crypto - Encryption layer using XChaCha20-Poly1305

4. Build & Run

Development Mode

Web Client

cd apps/web
npm start

Access at: http://localhost:3000

Desktop Client

cd apps/desktop
npm run dev

Mobile Clients

cd apps/mobile

# Android
npm run android

# iOS (macOS only)
npm run ios

Production Builds

Web Client

cd apps/web
npm run build

Output: apps/web/build directory

Desktop Client

cd apps/desktop

# Platform-specific builds
npm run build:linux
npm run build:mac
npm run build:win

Mobile Clients

cd apps/mobile

# Android APK
npm run build:android

# iOS IPA (macOS only)
npm run build:ios

Monorepo Commands

From the root directory, you can run:

# Build all packages
npm run build

# Run tests
npm test

# Clean builds
npm run clean

5. Deployment

Web Application Deployment

Recommended Platforms:

  • Vercel (optimized for React applications)
  • Netlify
  • Cloudflare Pages
  • Any static hosting (AWS S3, GitHub Pages, etc.)

Deployment Steps:

  1. Build the web client: cd apps/web && npm run build
  2. Deploy the build directory to your chosen platform
  3. Configure custom domain if needed
  4. Enable HTTPS (required for secure encryption)

Desktop Application Distribution

Distribution Channels:

  • GitHub Releases for direct downloads
  • Snap Store (Linux)
  • Microsoft Store (Windows)
  • Mac App Store (macOS)
  • Homebrew (macOS)

Build Configuration: Update apps/desktop/package.json with:

  • App identifiers
  • Code signing certificates
  • Publisher information

Mobile Application Distribution

Android:

  1. Generate signing key: keytool -genkey -v -keystore notesnook.keystore
  2. Configure apps/mobile/android/gradle.properties
  3. Build release APK/AAB: cd apps/mobile && npm run build:android -- --release

iOS:

  1. Configure in Xcode: Bundle ID, provisioning profiles
  2. Archive and distribute via TestFlight or App Store

Self-Hosted Sync Server (Advanced)

While Notesnook clients connect to the official sync server by default, you can explore:

  • The @notesnook/core package for API interactions
  • Custom sync server implementation (not officially provided)
  • Local-only usage without sync

6. Troubleshooting

Common Issues

1. Build Failures

Issue: npm install fails with native module errors Solution:

# Clear npm cache and rebuild
npm cache clean --force
rm -rf node_modules
npm install

2. Mobile Build Issues

Issue: React Native linking problems Solution:

cd apps/mobile
npm run clean
npm run setup:android  # or setup:ios

3. Database Errors

Issue: SQLite/IndexedDB initialization failures Solution:

  • Clear browser storage for web version
  • Reinstall app for mobile/desktop
  • Check apps/web/src/common/sqlite/sqlite-types.ts for SQLite configuration

4. Encryption Issues

Issue: "Failed to encrypt/decrypt data" Solution:

  • Verify @notesnook/sodium and @notesnook/crypto packages are properly installed
  • Check browser compatibility (WebAssembly support required)
  • Ensure consistent user login state

5. Sync Problems

Issue: Notes not syncing across devices Solution:

  • Verify internet connection
  • Check apps/mobile/app/services/notifications.ts for network state handling
  • Ensure you're using the same account on all devices
  • Check server status at https://status.notesnook.com

6. Editor Issues

Issue: TipTap editor not loading Solution:

  • Check apps/web/src/stores/editor-store.ts for editor state management
  • Verify @notesnook/editor package is correctly linked
  • Clear editor cache

Debugging

Enable Logging

// In development, enable debug logging
import { logger } from "@notesnook/logger";
logger.setLevel("debug");

Check Database State

// Access database instance
import { db } from "./common/db";
const notes = await db.notes.all();

Monitor Events

Notesnook uses an event system (EVENTS from @notesnook/core):

import { EVENTS } from "@notesnook/core";
import { AppEventManager } from "./common/app-events";

// Subscribe to events for debugging
AppEventManager.subscribe(AppEvents.DATABASE_UPDATED, (event) => {
  console.log("Database updated:", event);
});

Getting Help

Verification

To verify Notesnook's encryption claims:

← Project overviewView alternatives to notesnook →