StackBlitz SDK React Wrapper

Versão em Português

A unofficial React wrapper for the StackBlitz SDK that makes it easy to embed interactive code editors in React applications.

Table of Contents

• Installation
• Overview
• Components
  • Editor
  • ProjectEditor
  • ProjectIdEditor
• Helper Functions
• Usage Examples
• StackBlitz VM API
• Custom Hooks

Installation

npm install @stackblitz-react/sdk

Then, import the wrapper in your components:

import {stackBlitz} from '@stackblitz-react/sdk';

Overview

This wrapper provides a React interface for the StackBlitz SDK, allowing you to easily:

• Embed GitHub projects in your application
• Create projects with custom files
• Embed existing StackBlitz projects using their ID
• Interact with the editor in real-time through the VM API

Components

Editor

Component to embed GitHub projects in your application.

Props

Prop	Type	Default	Description
embedId	string	'stackblitz-container'	ID of the element where the editor will be embedded
github	string	-	GitHub repository in the format 'user/repository'
openFile	string/boolean	false	File to be initially opened
hideNavigation	boolean	false	Whether to hide navigation
hideExplorer	boolean	false	Whether to hide the file explorer
view	string	'both'	View type ('preview', 'editor', 'both')
height	string/number	500	Editor height
width	string/number	'100%'	Editor width
options	object	{}	Additional configuration options
onLoad	function	null	Callback called when the VM is loaded

Example

<stackBlitz.Editor
  embedId="github-editor-example"
  github="user/repository"
  openFile="README.md"
  height="400px"
  width="100%"
  view="editor"
  onLoad={(vm) => console.log('VM loaded', vm)}
/>

ProjectEditor

Component to create projects with custom files.

Props

Prop	Type	Default	Description
embedId	string	'stackblitz-project-editor'	ID of the element where the editor will be embedded
template	string	'javascript'	Project type (javascript, node, react, etc.)
title	string	'StackBlitz Project'	Project title
description	string	''	Project description
files	object	{}	Object with project files and their contents
openFile	string/boolean	false	File to be initially opened
hideNavigation	boolean	false	Whether to hide navigation
hideExplorer	boolean	false	Whether to hide the file explorer
view	string	'editor'	View type ('preview', 'editor', 'both')
height	string/number	500	Editor height
width	string/number	'100%'	Editor width
options	object	{}	Additional configuration options
onLoad	function	null	Callback called when the VM is loaded

Example

<stackBlitz.ProjectEditor
  embedId="custom-editor-example"
  template="node"
  title="Node.js Example"
  files={{
    'index.js': 'console.log("Hello from StackBlitz!");',
    'package.json': JSON.stringify({
      name: "node-starter",
      version: "0.0.0",
      private: true,
      scripts: {
        start: "node index.js"
      }
    }, null, 2)
  }}
  height="400px"
  width="100%"
  view="editor"
  onLoad={(vm) => console.log('VM loaded', vm)}
/>

ProjectIdEditor

Component to embed existing StackBlitz projects using their ID.

Props

Prop	Type	Default	Description
embedId	string	'stackblitz-project-id-editor'	ID of the element where the editor will be embedded
projectId	string	-	StackBlitz project ID to be embedded
openFile	string	-	File to be initially opened
hideNavigation	boolean	false	Whether to hide navigation
hideExplorer	boolean	false	Whether to hide the file explorer
view	string	'editor'	View type ('preview', 'editor', 'both')
height	string/number	500	Editor height
width	string/number	'100%'	Editor width
options	object	{}	Additional configuration options
onLoad	function	null	Callback called when the VM is loaded

Example

<stackBlitz.ProjectIdEditor
  embedId="project-id-editor-example"
  projectId="sdk-example-project"
  openFile="index.js"
  height="500px"
  width="100%"
  view="both"
  onLoad={(vm) => console.log('VM loaded', vm)}
/>

Helper Functions

The wrapper also provides helper functions to open projects in new tabs or embed them directly without React components.

openGithubProject

Opens a GitHub project in a new tab.

stackBlitz.openGithubProject('user/repository', {
  openFile: 'README.md'
});

openProject

Opens a custom project in a new tab.

stackBlitz.openProject({
  template: 'node',
  title: 'Example Node.js Project',
  description: 'A simple Node.js project',
  files: {
    'index.js': 'console.log("Hello from StackBlitz!");',
    'package.json': JSON.stringify({
      name: "node-starter",
      version: "0.0.0",
      private: true,
      scripts: {
        start: "node index.js"
      }
    }, null, 2)
  }
});

openProjectId

Opens a StackBlitz project by ID in a new tab.

stackBlitz.openProjectId('sdk-example-project', {
  openFile: 'index.html',
  view: 'both'
});

embedGithubProject

Embeds a GitHub project in a DOM element.

stackBlitz.embedGithubProject('element-id', 'user/repository', {
  openFile: 'README.md',
  height: 500
}).then(vm => {
  console.log('VM loaded', vm);
});

embedProject

Embeds a custom project in a DOM element.

stackBlitz.embedProject('element-id', {
  template: 'node',
  title: 'Node.js Project',
  files: {
    'index.js': 'console.log("Hello from StackBlitz!");'
  }
}, {
  height: 500
}).then(vm => {
  console.log('VM loaded', vm);
});

embedProjectId

Embeds a StackBlitz project by ID in a DOM element.

stackBlitz.embedProjectId('element-id', 'sdk-example-project', {
  openFile: 'index.js',
  height: 500
}).then(vm => {
  console.log('VM loaded', vm);
});

Usage Examples

Embedding a GitHub editor

import React, { useCallback, useState } from 'react';
import stackBlitz from '../stackblitzEditor';

export default function GithubEditorExample() {
  const [log, setLog] = useState([]);
  
  const handleVmReady = useCallback((vm) => {
    setLog(prev => [...prev, 'VM successfully initialized!']);
    
    // Example of interacting with the VM
    vm.editor.openFile('README.md');
  }, []);
  
  return (
    <div>
      <h1>GitHub Editor</h1>
      <stackBlitz.Editor
        embedId="github-editor-example"
        github="user/repository"
        openFile="README.md"
        height="400px"
        width="100%"
        view="editor"
        onLoad={handleVmReady}
      />
      <div>
        {log.map((entry, index) => <div key={index}>{entry}</div>)}
      </div>
    </div>
  );
}

Creating a project with custom files

import React from 'react';
import stackBlitz from '../stackblitzEditor';

export default function CustomProjectExample() {
  return (
    <div>
      <h1>Custom Project</h1>
      <stackBlitz.ProjectEditor
        embedId="custom-editor-example"
        template="node"
        title="Node.js Example"
        files={{
          'index.js': 'console.log("Hello from StackBlitz!");',
          'package.json': JSON.stringify({
            name: "node-starter",
            version: "0.0.0",
            private: true,
            scripts: {
              start: "node index.js"
            }
          }, null, 2)
        }}
        height="400px"
        width="100%"
        view="editor"
      />
    </div>
  );
}

StackBlitz VM API

When you use the onLoad callback, you get access to the StackBlitz VM API, which allows you to interact with the editor in real-time.

Main VM methods

applyFsDiff

Applies changes to the file system.

vm.applyFsDiff({
  create: {
    'newFile.js': 'console.log("New file");'
  },
  destroy: ['oldFile.js']
});

getFsSnapshot

Gets a current snapshot of the file system.

vm.getFsSnapshot().then(files => {
  console.log('Available files:', Object.keys(files));
});

editor.openFile

Opens a specific file in the editor.

vm.editor.openFile('index.js');

preview.getUrl

Gets the preview URL.

vm.preview.getUrl().then(url => {
  console.log('Preview URL:', url);
});

---

Limitations and Considerations

• The StackBlitz SDK only works in modern browsers.
• Large projects may take longer to load.

---

Contribution

Feel free to contribute to this wrapper by creating issues or pull requests.

License

MIT