createWorkspace

Factory function for creating Workspace instances from React components or elements.

createWorkspace is a factory function that creates a Workspace instance from a React component or element.

Plugin Required

The createWorkspace function performs static code analysis to extract dependencies. You need to install the required plugin before using it.

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

When to Use

By default, Codespark accepts code as strings or a files object with string-based content. While this approach works, it can become cumbersome and less maintainable—especially when dealing with complex components or multi-file demos.

createWorkspace solves this by allowing you to pass actual React components or elements as the preview source, rather than string literals. This provides better IDE support (syntax highlighting, type checking, auto-completion) and keeps your demo code co-located with your documentation.

Before — using string literals:

const files = {
  './App.tsx': `import Button from './button';

export default function App() {
  return <Button />
}`,
  './button.tsx': '// ...component code as a string'
};

<Codespark files={files} />

After — using createWorkspace:

button.tsx

export default function Button() {
  return <button className="btn">Click me</button>;
}

import Button from './button';

const workspace = createWorkspace(<Button />);

<CodesparkProvider workspace={workspace} />

With this approach, you import and use components just like you would in any React application.

How It Works

When used with the @codespark/plugin-rollup plugin, createWorkspace receives scanned code information through its this context:

The plugin scans your component file and extracts:
- The component's source code
- Import statements
- Local variable definitions
- Referenced files
createWorkspace processes this information based on the mode option:
- packed: Combines imports, locals, and the component into a single file
- source: Uses only the original source file
- raw: Uses the raw scanned code
A new Workspace instance is created with the processed code

Usage

The plugin supports three types of source arguments: React Component, React Element, and Inline Function. Each type is transformed differently to extract the necessary code information.

React Component

Pass a component reference directly. The plugin extracts the component name and its local dependencies.

const  = () => <>Click</>;

();

createWorkspace.call(
  {
    __scanned: {
      entry: {
        code: 'MyButton',
        locals: ['const MyButton = () => <button>Click</button>;'],
        imports: []
      },
      files: {}
    }
  },
  MyButton
);

new Workspace({
  files: {
    './App.tsx': `const MyButton = () => <button>Click</button>;

export default MyButton;`
  }
});

new Workspace({
  files: { './App.tsx': '' }
})

new Workspace({
  files: { './App.tsx': 'MyButton' }
})

React Element

Wrap a component in JSX syntax. The plugin extracts the element code and resolves its dependencies.

const  = () => <>Click</>;

(< />);

createWorkspace.call(
  {
    __scanned: {
      entry: {
        code: '<MyButton />',
        locals: ['const MyButton = () => <button>Click</button>;'],
        imports: []
      },
      files: {}
    }
  },
  <MyButton />
);

new Workspace({
  files: {
    './App.tsx': `const MyButton = () => <button>Click</button>;

export default function App() {
  return <MyButton />
};`
  }
});

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

new Workspace({
  files: { './App.tsx': '<MyButton />' }
});

Inline Function

Pass an arrow function or function expression directly. Useful for simple demos without defining a separate component.

(() => <>Click</>);

createWorkspace.call(
  {
    __scanned: {
      entry: {
        code: '() => <button>Click</button>',
        locals: [],
        imports: []
      },
      files: {}
    }
  },
  () => <button>Click</button>
);

new Workspace({
  files: {
    './App.tsx': `export default () => <button>Click</button>;`
  }
});

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

new Workspace({
  files: { './App.tsx': '() => <button>Click</button>' }
});

With External Imports

When your component uses external libraries, the plugin extracts the import statements.

import {  } from 'react';

(function () {
  const [] = (0);

  return <>{}</>;
});

createWorkspace.call(
  {
    __scanned: {
      entry: {
        code: 'function Counter() {\n  const [count] = useState(0);\n\n  return <button>{count}</button>;\n}',
        locals: [],
        imports: ["import { useState } from 'react';"]
      },
      files: {}
    }
  },
  function Counter() { /* ... */ }
);

new Workspace({
  files: {
    './App.tsx': `import { useState } from 'react';

export default function Counter() {
  const [count] = useState(0);

  return <button>{count}</button>;
};`
  }
});

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

new Workspace({
  files: {
    './App.tsx': `function Counter() {
  const [count] = useState(0);

  return <button>{count}</button>;
}`
  }
});

With Local File Imports

When your component imports from local files, the plugin resolves and includes those files.

Button.tsx

export default function Button() {
  return <button>Click</button>;
}

Demo.tsx

import  from './Button';

createWorkspace(< />);

createWorkspace.call(
  {
    __scanned: {
      entry: {
        code: '<Button />',
        locals: [],
        imports: []
      },
      files: {
        './Button': 'export default function Button() {\n  return <button>Click</button>;\n}'
      }
    }
  },
  <Button />
);

new Workspace({
  files: {
    './App.tsx': `export default function App() {
  return <Button />
};`,
    './Button': 'export default function Button() {\n  return <button>Click</button>;\n}'
  }
});

new Workspace({
  files: {
    './App.tsx': 'export default function Button() {\n  return <button>Click</button>;\n}'
  }
});

new Workspace({
  files: {
    './App.tsx': '<Button />',
    './Button': 'export default function Button() {\n  return <button>Click</button>;\n}'
  }
});

With Nested Dependencies

The plugin recursively resolves dependencies. If a local component uses another local component, both are included.

const  = () => <>Inner</>;
const  = () => < />;

(< />);

createWorkspace.call(
  {
    __scanned: {
      entry: {
        code: '<Outer />',
        locals: [
          'const Inner = () => <span>Inner</span>;',
          'const Outer = () => <Inner />;'
        ],
        imports: []
      },
      files: {}
    }
  },
  <Outer />
);

new Workspace({
  files: {
    './App.tsx': `const Inner = () => <span>Inner</span>;
const Outer = () => <Inner />;

export default function App() {
  return <Outer />
};`
  }
});

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

new Workspace({
  files: { './App.tsx': '<Outer />' }
});

Parameters

source

The React component or element to create a workspace from.

Type	Required	Since
`ComponentType \| ReactElement`	Yes	v1.0.0

config

Configuration options for the workspace.

Type	Required	Since
`CreateWorkspaceConfig`	No	v1.0.0

Config

id

Unique identifier for the workspace instance.

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

(, { : 'my-demo-workspace' });

name

Entry file name/path for the workspace.

Type	Default	Since
`string`	`'./App.tsx'`	v1.0.0

(, { : './Demo.tsx' });

mode

Code processing mode that determines how the source code is bundled.

Type	Default	Since
`'raw' \| 'source' \| 'packed'`	`'packed'`	v1.0.0

'packed': Bundle imports, local definitions, and the component into a single file (recommended for most use cases)
'source': Use only the original source file content without bundling dependencies
'raw': Use the raw scanned code as-is, including all transformations applied by the rollup plugin

// Use packed mode (default) - bundles everything together
(, { : 'packed' });

// Use source mode - only the original source file
(, { : 'source' });

// Use raw mode - raw scanned code
(, { : 'raw' });

framework

Framework to use for code analysis and compilation.

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

(, { :  });

Return Value

Returns a new Workspace instance configured with the extracted code.

Type
`Workspace`

Types

interface CreateWorkspaceConfig {
  /**
   * Unique identifier for the workspace instance
   */
  id?: string;
  /**
   * Framework to use for code analysis and compilation
   */
  framework?: Framework | (new () => Framework) | string;
  /**
   * Entry file name/path
   * @default './App.tsx'
   */
  name?: string;
  /**
   * Code processing mode:
   * - 'raw': Use the raw scanned code as-is
   * - 'source': Use only the source file content
   * - 'packed': Bundle imports, locals, and component into a single file
   * @default 'packed'
   */
  mode?: 'raw' | 'source' | 'packed';
}

On this page