Skip to main content

JavaScript SDK

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

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.

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:

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

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

SDK demo: working with GitHub projects

Use the openGithubProject and embedGithubProject SDK methods to open or embed public GitHub repositories as StackBlitz 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:

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

// 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', {
newWindow: false,
});

Generate and embed new projects

SDK demo: creating new projects

Use the openProject and embedProject SDK methods to dynamically 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:

sdk.openProject(
'embed',
{
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:

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

Options reference

Project

An object defining the contents and settings of a StackBlitz project.

PropertyRequired TypeDescription
titleYesStringThe project title.
descriptionYesStringA short description for this project.
templateYesProjectTemplate (String)Determines how code compiles and runs.
filesYesProjectFiles (Object)Project files and their contents.
dependenciesNoProjectDependencies (Object)Specifies npm dependencies (EngineBlock only).
settingsNoProjectSettings (Object)Code compilation behavior (EngineBlock only).

ProjectTemplate

A string representing a supported template type.

Each template has its own rules for compiling source files, and requires specific files to be present.

Template nameEnvironmentRequired files
'angular-cli'EngineBlockindex.html and main.ts
'create-react-app'EngineBlockindex.html and index.js
'html'EngineBlockindex.html
'javascript'EngineBlockindex.html and index.js
'polymer'EngineBlockindex.html
'typescript'EngineBlockindex.html and index.ts
'vue'EngineBlockpublic/index.html and src/main.js
'node'WebContainersNo requirements

ProjectFiles

A plain object representing file paths and their contents.

  • Object keys: strings representing file paths (from the root of the project).
  • Object values: strings representing file contents (text only).
Supported file types

Only plain text files (including code, data, and SVG images) are supported in ProjectFiles.

Binary files (such as archive formats, binaries and executables, bitmap images, audio and video files) are not supported at this time.

ProjectDependencies

A plain object representing npm packages and their versions, to be installed at runtime when the project loads.

  • Object keys: strings representing npm package names.
  • Object values: strings representing npm package version specifiers.
Environment differences

ProjectDependencies are only used in the EngineBlock environment.

In projects running on WebContainers, they are ignored, and dependencies listed in the package.json file in ProjectFiles are resolved and installed instead.

ProjectSettings

Compilation settings for EngineBlock projects.

PropertyTypeDescriptionDefault
compile.trigger'auto', 'save', or 'keystroke'Determines when the source changes should trigger compilation.'auto'
compile.action'hmr' or 'refresh'Determines how compiled changes should be injected.'hmr'
compile.clearConsoleBooleanDetermines if the Console should be cleared after compilation.true

In projects running on WebContainers (which use template: 'node'), only compile.trigger is used. This affects the time at which file changes in the editor are written to the virtual filesystem.

OpenOptions

Display options available when opening a project in a new window.

PropertyTypeDescriptionDefault Value
clickToLoadBooleanShows a UI dialog asking users to run the project.false
devToolsHeightNumberSets the Console height (from 0 to 100). EngineBlock only.-
hideDevToolsBooleanHides the Console completely. EngineBlock only.false
hideExplorerBooleanHides the ActivityBar.false
newWindowBooleanOpens the project in a new tab.true
openFileOpenFileOption (String or Array)Specifies which file(s) to open in the editor and code lines to highlight.-
originStringStackBlitz Enterprise Edition: sets the origin URL of the StackBlitz EE instance.-
showSidebarBooleanShows the Sidebar as open (true) or closed (false) on page load.-
terminalHeightNumberSets the Terminal height (from 0 to 100). WebContainers only.30
themeUiThemeOption (String)Sets the desired color theme.see UiThemeOption
viewUiViewOption (String)Sets the initial UI view: editor, preview, or both.see UiThemeOption

EmbedOptions

Display options available when embedding a project in an iframe.

PropertyTypeDescriptionDefault Value
clickToLoadBooleanShows a UI dialog asking users to run the project.false
devToolsHeightNumberSets Console height (from 0 to 100). EngineBlock only.-
heightNumberSets the height of the embed iframe.300
hideDevToolsBooleanHides the Console completely. EngineBlock only.false
hideExplorerBooleanHides the ActivityBar.false
hideNavigationBooleanHides the preview URL in embeds.false
openFileOpenFileOption (String or Array)Specifies which file(s) to open in the editor and code lines to highlight.-
originStringStackBlitz Enterprise Edition: sets the origin URL of the StackBlitz EE instance.-
showSidebarBooleanShows the Sidebar as open (true) or closed (false) on page load.-
terminalHeightNumberSets Terminal height (from 0 to 100). WebContainers only.30
themeUiThemeOption (String)Sets the desired color theme.see UiThemeOption
viewUiViewOption (String)Sets the initial UI view: editor, preview, or both.see UiViewOption
widthNumberSets the width of the embed iframe.100%

OpenFileOption

Specifies file paths to open in the editor. It can be a single string or an array of strings, where each string is a comma-separated list of file paths.

File paths can include lines of code to be highlighted, using the format {path}:L{start} for a single line and {path}:L{start}-L{end} for a range. Any file change will remove the highlight selection.

Example with a single file:

  // Opens a single file
openFile: 'src/App.tsx',

Example with a single file with third line highlighted:

  // Opens a single file and highlights the third line
openFile: 'src/App.tsx:L3',

Example with a single file with a range (lines 5-8) highlighted:

  // Opens a single file and highlights a range
openFile: 'src/App.tsx:L5-L8',

Example with three editor tabs (the last file is displayed):

  // Opens three editor tabs with the last file displayed
openFile: 'index.html,package.json,src/App.tsx',

Example with three editor panes with one tab in each pane:

  // Opens three side-by-side editor panes with one tab in each pane
openFile: ['index.html', 'package.json', 'src/App.tsx'],

Example with two editor panes with two tabs in each pane:

  // Opens two editor panes with two tabs in each pane
openFile: ['index.html,package.json', 'src/App.tsx,src/App.css'],

UiThemeOption

The name of the color theme supported by the embedded editor.

ValueDescription
'default'Uses the default theme (currently: 'dark').
'dark'The built-in dark theme.
'light'The built-in light theme.

UiViewOption

Controls the display mode of the project.

This only declares an intent, and the available values may behave differently depending on:

  • the viewport width;
  • whether the project is rendered in a tab (“standard layout”) or iframe (“embed layout”).
ValueDescription
'default'Shows Preview and Editor on large viewports, Editor only in small viewports
'preview'Shows the Preview only (embed layout only)
'editor'Shows the Editor only (embed and standard layouts)