Workspace

Workspace is the core class that manages a virtual file system for code editing and live preview. It handles file CRUD operations, tracks the currently active file, and emits events for file changes and compilation results.

import { Workspace } from '@codespark/react';

Basic Usage

Create a new Workspace instance with an entry file and initial files:

import {  } from '@codespark/react';

const  = new ({
  : './App.tsx',
  : {
    './App.tsx': 'export default () => <div>Hello</div>'
  }
});

Constructor

new Workspace(config)

Creates a new Workspace instance.

Parameter	Type	Description	Since
`config`	`WorkspaceInit`	Configuration object for the workspace	v1.0.0

const  = new ({
  : 'my-workspace',
  : './App.tsx',
  : {
    './App.tsx': 'export default () => <div>Hello</div>',
    './Button.tsx': 'export const Button = () => <button>Click</button>'
  },
  : 'react',
  : false
});

WorkspaceInit Options

entry

Entry file path, the main file to compile and render.

Type	Required	Since
`string`	Yes	v1.0.0

new ({
  : './App.tsx',
  : { './App.tsx': '...' }
});

files

Initial files mapping, where keys are file paths and values are file contents.

Type	Required	Since
`Record<string, string>`	Yes	v1.0.0

new ({
  : './App.tsx',
  : {
    './App.tsx': 'import { Button } from "./Button";\nexport default () => <Button />',
    './Button.tsx': 'export const Button = () => <button>Click</button>'
  }
});

id

Unique identifier for the workspace instance.

Type	Default	Since
`string`	Auto-generated	v1.0.0

new ({
  : 'my-workspace',
  : './App.tsx',
  : { './App.tsx': '...' }
});

framework

Framework to use for code analysis and compilation.

Type	Default	Since
`Framework \| (new () => Framework) \| string`	-	v1.0.0

import {  } from '@codespark/framework/html';
import {  } from '@codespark/react';

new ({
  : './App.tsx',
  : { './App.tsx': '...' },
  : 
});

OPFS

Whether to use Origin Private File System (OPFS) for file persistence.

Type	Default	Since
`boolean`	`false`	v1.0.0

new ({
  : './App.tsx',
  : { './App.tsx': '...' },
  : true
});

Properties

All the properties from workspace instance you can access are getters, it mean that they are readonly.

workspace.id

Unique identifier for the workspace instance.

Type	Since
`string`	v1.0.0

workspace.entry

Entry file path.

Type	Since
`string`	v1.0.0

workspace.files

Current files in the workspace.

Type	Since
`Record<string, string>`	v1.0.0

workspace.framework

Framework used for compilation.

Type	Since
`Framework \| (new () => Framework) \| string`	v1.0.0

workspace.currentFile

Currently active file in the editor.

Type	Since
`FileNode`	v1.0.0

interface FileNode {
  type: 'file';
  name: string;      // File name (e.g., 'App.tsx')
  path: string;      // Full path (e.g., './App.tsx')
  code: string;      // File content
  language?: string; // Language identifier
}

workspace.initialFiles

The initial files mapping provided at construction time.

Type	Since
`Record<string, string>`	v1.0.0

Methods

setFile(path, content)

Update or create a single file. Automatically creates parent folders if needed.

Parameter	Type	Description
`path`	`string`	File path
`content`	`string`	File content

.('./App.tsx', 'export default () => <div>New content</div>');

setFiles(files)

Replace all files in the workspace. Also updates initialFiles.

Parameter	Type	Description
`files`	`Record<string, string>`	New files mapping

.({
  './App.tsx': '...',
  './Button.tsx': '...'
});

setCurrentFile(path)

Set the currently active file.

Parameter	Type	Description
`path`	`string`	File path to set as current

.('./Button.tsx');

renameFile(oldPath, newName)

Rename a file or folder. When renaming a folder, all files within it are also renamed.

Parameter	Type	Description
`oldPath`	`string`	Current file/folder path
`newName`	`string`	New name (not full path)

.('./Button.tsx', 'MyButton.tsx');
// Result: ./Button.tsx -> ./MyButton.tsx

.('components', 'ui');
// Result: components/Button.tsx -> ui/Button.tsx

deleteFile(path)

Delete a file or folder. When deleting a folder, all files within it are also deleted.

Parameter	Type	Description
`path`	`string`	File/folder path to delete

.('./Button.tsx');

on(event, callback)

Subscribe to workspace events. Returns an unsubscribe function.

Parameter	Type	Description
`event`	`keyof WorkspaceEvent`	Event name
`callback`	`WorkspaceEvent[E]`	Event handler

Returns
`() => void` (unsubscribe function)

const  = .('compiled',  => {
  .('Compiled:', );
});

// Later: unsubscribe();

off(event, callback)

Unsubscribe from workspace events.

Parameter	Type	Description
`event`	`keyof WorkspaceEvent`	Event name
`callback`	`WorkspaceEvent[E]`	Event handler to remove

const  = () => {};
.('compiled', );
.('compiled', ); // unsubscribe

Events

The Workspace class emits the following events:

Event	Callback Signature	Description
`compiled`	`(code: string) => void`	Fired when code compilation succeeds
`compileError`	`(error: Error) => void`	Fired when code compilation fails
`fileChange`	`(path: string, content: string) => void`	Fired when a single file is changed
`filesChange`	`(files: Record<string, string>) => void`	Fired when all files are replaced
`fileRename`	`(oldPath: string, newPath: string) => void`	Fired when a file or folder is renamed
`fileDelete`	`(path: string) => void`	Fired when a file or folder is deleted
`currentFileChange`	`(file: FileNode) => void`	Fired when the currently active file changes

Event Usage Example

import {  } from '@codespark/react';

const  = new ({
  : './App.tsx',
  : { './App.tsx': '...' }
});

// Subscribe to compilation events
.('compiled',  => {
  .('Code compiled successfully');
});

.('compileError',  => {
  .('Compilation failed:', .);
});

// Subscribe to file change events
.('fileChange', (, ) => {
  .(`File ${} changed`);
});

.('currentFileChange',  => {
  .(`Now editing: ${.}`);
});

Types

interface WorkspaceInit {
  id?: string;
  framework?: Framework | (new () => Framework) | string;
  entry: string;
  files: Record<string, string>;
  OPFS?: boolean;
}

interface WorkspaceEvent {
  compiled: (code: string) => void;
  compileError: (error: Error) => void;
  fileChange: (path: string, content: string) => void;
  filesChange: (files: Record<string, string>) => void;
  fileRename: (oldPath: string, newPath: string) => void;
  fileDelete: (path: string) => void;
  currentFileChange: (file: FileNode) => void;
}

interface FileNode {
  type: 'file';
  name: string;
  path: string;
  code: string;
  language?: string;
}

interface FolderNode {
  type: 'folder';
  name: string;
  path: string;
  children?: FileTreeNode[];
}

type FileTreeNode = FileNode | FolderNode;