@workspace-fs/react

React hooks for Workspace-FS - Multi-project file system management

Installation

npm install @workspace-fs/react @workspace-fs/core
# or
yarn add @workspace-fs/react @workspace-fs/core
# or
pnpm add @workspace-fs/react @workspace-fs/core

Key Concepts

The WorkspaceProvider requires a pre-configured WorkspaceFileSystem instance. You are responsible for:

1. Creating the workspace instance
2. Initializing it with your providers
3. Passing it to the WorkspaceProvider

This gives you full control over the workspace configuration and lifecycle.

Quick Start

import { WorkspaceProvider, useWorkspace, useActiveProject } from '@workspace-fs/react';
import { WorkspaceFileSystem } from '@workspace-fs/core';
import { memoryProvider } from '@firesystem/memory/provider';
import { indexedDBProvider } from '@firesystem/indexeddb/provider';

// Create your workspace instance
const workspace = new WorkspaceFileSystem();

// Register your providers first
workspace.registerProvider(memoryProvider);
workspace.registerProvider(indexedDBProvider);

// Then initialize
await workspace.initialize();

function App() {
  return (
    <WorkspaceProvider workspace={workspace}>
      <Workspace />
    </WorkspaceProvider>
  );
}

function Workspace() {
  const { loadProject, setActiveProject } = useWorkspace();
  const { project, fs } = useActiveProject();
  
  const handleCreateProject = async () => {
    const project = await loadProject({
      id: `project-${Date.now()}`,
      name: 'My Project',
      source: { type: 'memory', config: {} }
    });
    await setActiveProject(project.id);
  };
  
  if (!fs) {
    return <button onClick={handleCreateProject}>Create Project</button>;
  }
  
  return (
    <div>
      <h1>{project?.name}</h1>
      {/* Use fs to read/write files */}
    </div>
  );
}

Available Hooks

Core Hooks

• useWorkspace() - Main workspace management
• useProjects() - Reactive list of all projects
• useProject(id) - Access specific project by ID
• useActiveProject() - Current active project with fs shortcut
• useWorkspaceEvents(event, callback) - Listen to workspace events

Optimization Hooks

• useProjectSelector(id, selector) - Select specific data from a project
• useProjectsSelector(selector) - Select data from projects list
• useActiveProjectSelector(selector) - Select data from active project

Examples

List All Projects

function ProjectList() {
  const { projects, activeProjectId } = useProjects();
  
  return (
    <ul>
      {projects.map(project => (
        <li key={project.id} className={project.id === activeProjectId ? 'active' : ''}>
          {project.name} ({project.source.type})
        </li>
      ))}
    </ul>
  );
}

Listen to File Changes

function FileWatcher() {
  useWorkspaceEvents('project:file:written', ({ projectId, path }) => {
    console.log(`File ${path} saved in project ${projectId}`);
  });
  
  return null;
}

Optimized Selectors

function ProjectName({ projectId }: { projectId: string }) {
  // Only re-renders when name changes, not on any project update
  const name = useProjectSelector(projectId, p => p?.name);
  
  return <span>{name}</span>;
}

Complete Example

import { WorkspaceProvider, useWorkspace, useProjects } from '@workspace-fs/react';
import { WorkspaceFileSystem } from '@workspace-fs/core';
import { memoryProvider } from '@firesystem/memory/provider';
import { indexedDBProvider } from '@firesystem/indexeddb/provider';

// Create and configure workspace outside of React
const workspace = new WorkspaceFileSystem();

// Initialize before rendering
async function initApp() {
  // Register providers
  workspace.registerProvider(memoryProvider);
  workspace.registerProvider(indexedDBProvider);
  
  // Initialize workspace
  await workspace.initialize();
  
  // Now render your app
  const root = ReactDOM.createRoot(document.getElementById('root'));
  root.render(
    <WorkspaceProvider workspace={workspace}>
      <App />
    </WorkspaceProvider>
  );
}

initApp();

API Reference

WorkspaceProvider

The context provider that makes the workspace available to all child components.

interface WorkspaceProviderProps {
  children: React.ReactNode;
  workspace: WorkspaceFileSystem; // Required - your configured workspace instance
}

Hooks

All hooks require the component to be wrapped in a WorkspaceProvider.

License

MIT