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:

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:

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

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

<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:

<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:

• TypeScript demo
• JavaScript demo

openProjectId(projectId, openOptions)

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

Argument	Required	Type	Description
projectId	Yes	String	The ID of the project to open.
openOptions	No	OpenOptions (Object)	Display options for the StackBlitz editor.

Example:

// 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.

Argument	Required	Type	Description
elementOrId	Yes	String or HTMLElement	Element to replace with an iframe, or its id attribute.
projectId	Yes	String	The ID of the project to open.
embedOptions	No	EmbedOptions (Object)	Display options for StackBlitz embeds.

Example:

// 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:

• TypeScript demo
• JavaScript demo

openGithubProject(repoPath, openOptions)

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

Argument	Required	Type	Description
repoPath	Yes	String	The repository path (with optional branch/tag/commit/folder).
openOptions	No	OpenOptions (Object)	Display options for the StackBlitz editor.

Example:

// 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.

Argument	Required	Type	Description
elementOrId	Yes	String or HTMLElement	Element to replace with an iframe, or its id attribute.
repoPath	Yes	String	The repository path (with optional branch/tag/commit/folder).
embedOptions	No	EmbedOptions (Object)	Display options for StackBlitz embeds.

Example:

// 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:

• TypeScript demo
• JavaScript demo

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).

Argument	Required	Type	Description
project	Yes	Project (Object)	Project data and settings.
openOptions	No	OpenOptions (Object)	Display options for the StackBlitz editor.

Example:

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.

Argument	Required	Type	Description
elementOrId	Yes	String or HTMLElement	Element to replace with an iframe, or its id attribute.
project	Yes	Project (Object)	Project data and settings.
embedOptions	No	EmbedOptions (Object)	Display options for StackBlitz embeds.

Example:

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,
  },
);