Skip to content

JavaScript SDK

The StackBlitz JavaScript SDK lets you programmatically create StackBlitz projects to be opened in a new window or embedded in your docs, example pages, or blog posts. Once embedded, the projects can be controlled by using the SDK’s VM interface.

Interactive Tutorial

In addition to this guide, you can also play with our interactive StackBlitz SDK tutorial (build with TutorialKit): StackBlitz SDK Tutorial

Install the SDK

The SDK is 3kB gzipped and can be installed from npm:

sh
npm install @stackblitz/sdk

If you’re using a JavaScript bundler (for instance webpack or Vite), you should be able to import the SDK in your JavaScript modules:

js
import sdk from '@stackblitz/sdk';
sdk.embedProject(/* … */);

You can also import the SDK from jsDeliver or UNPKG directly in an HTML page:

html
<script type="module">
  import sdk from 'https://unpkg.com/@stackblitz/sdk@1/bundles/sdk.m.js';
  sdk.embedProject(/* … */);
</script>

Or load the UMD bundle, which will add a global window.StackBlitzSDK object:

html
<script src="https://unpkg.com/@stackblitz/sdk@1/bundles/sdk.umd.js"></script>
<script>
  StackBlitzSDK.embedProject(/* … */);
</script>

Open and embed StackBlitz projects

Use the openProjectId and embedProjectId SDK methods to open or embed an existing StackBlitz project.

DEMO

Check this demo of using StackBlitz SDK to open and embed StackBlitz projects:

openProjectId(projectId, openOptions)

Opens an existing StackBlitz project in a new tab (or in the current window).

ArgumentRequiredTypeDescription
projectIdYesStringThe ID of the project to open.
openOptionsNoOpenOptions (Object)Display options for the StackBlitz editor.

Example:

js
// Opens https://stackblitz.com/edit/my-cool-project in the current window
// with the Preview pane hidden
sdk.openProjectId('my-cool-project', {
  newWindow: false,
  openFile: 'src/App.tsx',
  view: 'editor',
});

embedProjectId(elementOrId, projectId, embedOptions)

Embeds an existing StackBlitz project in the specified HTML element on the current page. Returns a promise resolving its VM instance.

ArgumentRequiredTypeDescription
elementOrIdYesString or HTMLElementElement to replace with an iframe, or its id attribute.
projectIdYesStringThe ID of the project to open.
embedOptionsNoEmbedOptions (Object)Display options for StackBlitz embeds.

Example:

js
// Replaces the HTML element with the id of "embed"
// with https://stackblitz.com/edit/my-cool-project embedded in an iframe,
sdk.embedProjectId('embed', 'my-cool-project', {
  openFile: 'index.ts,src/App.tsx',
});

Open and embed GitHub repositories

Use the openGithubProject and embedGithubProject SDK methods to open or embed public GitHub repositories as StackBlitz projects.

DEMO

Check this demo of using StackBlitz SDK to work with GitHub projects:

openGithubProject(repoPath, openOptions)

Opens a project from GitHub in StackBlitz (in a new tab or in the current window).

ArgumentRequiredTypeDescription
repoPathYesStringThe repository path (with optional branch/tag/commit/folder).
openOptionsNoOpenOptions (Object)Display options for the StackBlitz editor.

Example:

js
// Imports https://github.com/username/repository-name to StackBlitz,
// and opens the resulting StackBlitz project in the current tab
sdk.openGithubProject('username/repository-name', {
  newWindow: false,
});

// Imports the 'examples/getting-started' sub-folder of the 'main' branch of
// the https://github.com/username/repository-name repository to StackBlitz,
// and opens the resulting StackBlitz project in a new tab
sdk.openGithubProject('username/repository-name/tree/main/examples/getting-started');

embedGithubProject(elementOrId, repoPath, embedOptions)

Embeds a project from GitHub on the current page. Returns a promise resolving its VM instance.

ArgumentRequiredTypeDescription
elementOrIdYesString or HTMLElementElement to replace with an iframe, or its id attribute.
repoPathYesStringThe repository path (with optional branch/tag/commit/folder).
embedOptionsNoEmbedOptions (Object)Display options for StackBlitz embeds.

Example:

js
// Imports https://github.com/username/repository-name to StackBlitz,
// and embeds the resulting StackBlitz project in the current page
sdk.embedGithubProject('embed', 'username/repository-name', {
  terminalHeight: 45,
});

Generate and embed new projects

Use the openProject and embedProject SDK methods to dynamically create new projects.

DEMO

Check this demo of using StackBlitz SDK to create new projects:

Data persistence

New projects are not persisted on StackBlitz, and only live in the browser’s memory — unless a user forks the project to save it in their StackBlitz account.

openProject(project, openOptions)

Creates a new project and opens it in a new tab (or in the current window).

ArgumentRequiredTypeDescription
projectYesProject (Object)Project data and settings.
openOptionsNoOpenOptions (Object)Display options for the StackBlitz editor.

Example:

js
sdk.openProject(
  {
    title: 'JS Starter',
    description: 'Blank starter project for building ES6 apps.',
    template: 'javascript',
    files: {
      'index.html': `<div id="app"></div>`,
      'index.js': `import './style.css';
const appDiv = document.getElementById('app');
appDiv.innerHTML = '<h1>JS Starter</h1>';`,
      'style.css': `body { font-family: system-ui, sans-serif; }`,
    },
    settings: {
      compile: {
        trigger: 'auto',
        clearConsole: false,
      },
    },
  },
  {
    newWindow: false,
    openFile: ['index.js', 'index.html,style.css'],
  },
);

embedProject(elementOrId, project, embedOptions)

Creates a new project and embeds it in the current page. Returns a promise resolving its VM instance.

ArgumentRequiredTypeDescription
elementOrIdYesString or HTMLElementElement to replace with an iframe, or its id attribute.
projectYesProject (Object)Project data and settings.
embedOptionsNoEmbedOptions (Object)Display options for StackBlitz embeds.

Example:

js
sdk.embedProject(
  'embed',
  {
    title: 'Node Starter',
    description: 'A basic Node.js project',
    template: 'node',
    files: {
      'index.js': `console.log('Hello World!');`,
      'package.json': `{
      "name": "my-project",
      "scripts": { "hello": "node index.js", "start": "serve node_modules" },
      "dependencies": { "serve": "^14.0.0" },
      "stackblitz": { "installDependencies": true, "startCommand": "npm start" },
    }`,
    },
  },
  {
    clickToLoad: true,
    openFile: 'index.js',
    terminalHeight: 50,
  },
);