use-desktop-db 📁

Turn a folder on your user's physical hard drive into a reactive NoSQL database. Zero cloud, zero data-loss, true local-first state for React.

Powered by the experimental File System Access API, this package lets you bypass localStorage and IndexedDB entirely. You can read and write raw .json files directly to the user's local machine, while keeping the Developer Experience as simple as useState.

✨ Features

• 🌍 Zero Cloud: No backend, no database hosting. Data lives physically on the user's device.
• 🛡️ Secure Sandbox: Users explicitly grant access to a specific folder. Your app cannot read the rest of their drive.
• ⚛️ Reactive Hook: Read, insert, update, and remove data just like standard React state, but with physical file side-effects.
• 🔌 Offline First: Works perfectly without an internet connection.

📦 Installation

npm install use-desktop-db

🚀 Quick Start

1. The Security Gate (Provider)

Because browsers restrict background file access, you must wrap your app in the DesktopDBProvider and let the user click a button to grant folder access.

import { DesktopDBProvider, useDesktopDBAuth } from 'use-desktop-db';

function ConnectionScreen() {
  const { connect, isConnected } = useDesktopDBAuth();

  if (!isConnected) {
    return <button onClick={connect}>Select Local Folder</button>;
  }

  return <Dashboard />;
}

export default function App() {
  return (
    <DesktopDBProvider>
      <ConnectionScreen />
    </DesktopDBProvider>
  );
}

2. The Data Engine (Hook)

Once connected, drop the useDesktopDB hook into any component. Pass the name of your collection (e.g., 'invoices'), and the hook will automatically create or read invoices.json in the selected folder.

import { useState } from 'react';
import { useDesktopDB } from 'use-desktop-db';

interface Note {
  id: number;
  text: string;
}

function Dashboard() {
  // Connects to 'my_notes.json' in the user's chosen folder
  const { data, insert, remove, isLoading } = useDesktopDB<Note>('my_notes');
  const [input, setInput] = useState('');

  const handleSave = () => {
    insert({ id: Date.now(), text: input });
    setInput('');
  };

  return (
    <div>
      <h2>Local Notes</h2>
      <input value={input} onChange={e => setInput(e.target.value)} />
      <button onClick={handleSave}>Save to Disk</button>

      {isLoading ? <p>Reading file...</p> : (
        <ul>
          {data.map(note => (
            <li key={note.id}>
              {note.text} <button onClick={() => remove(note.id)}>Delete</button>
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}

🧰 API Reference

useDesktopDBAuth()

Provides the security context to request access to the user's hard drive.

| Property | Type | Description | | :--- | :--- | :--- | | connect() | Promise<void> | Triggers the browser's native "Select Folder" prompt. | | disconnect() | void | Revokes the current directory access and clears the state. | | isConnected | boolean | true if the user has successfully granted folder access. | | dirHandle | FileSystemDirectoryHandle | The raw browser file system handle (for advanced manual use). |

useDesktopDB<T>(collectionName)

The core data engine. Note: Your data type <T> must include an id field (string or number).

| Parameter / Return | Type | Description | | :--- | :--- | :--- | | collectionName | string | (Argument) The name of the .json file to create/read (e.g., 'invoices'). | | data | T[] | The parsed array of objects currently saved on the hard drive. | | insert(item) | Promise<void> | Adds a new object to the array and physically saves the file. | | update(id, item) | Promise<void> | Updates an existing object by id and physically saves the file. | | remove(id) | Promise<void> | Deletes an object by id and physically saves the file. | | isLoading | boolean | true while the browser is actively reading the disk. | | error | string \| null | Contains the error message if file access fails. |

⚠️ Browser Support

This package uses the File System Access API. It is currently fully supported on Chrome, Edge, and Opera (Desktop). Safari and Firefox currently have limited support for the write capabilities.

📜 License

MIT