Skip to main content

Javascript SDK

Wouldn't it be great if you could create & embed StackBlitz projects on-demand in your docs, examples, blog posts... In just a couple lines of code?

This is exactly what our JavaScript SDK (Software Development Kit) allows you to do. Even better, the SDK even gives you full control of the StackBlitz VM - allowing you to build rich & interactive experiences around your projects.

The SDK is 2kb gzipped(!) and you can install it from NPM:

npm install --save @stackblitz/sdk

Or add a script tag to the UMD build on jsDelivr/Unpkg — the SDK will be available on window as StackBlitzSDK:

<script src="https://unpkg.com/@stackblitz/sdk/bundles/sdk.umd.js"></script>

Supported Project Types#

Here is our current list of supported types for SDK imports:

  • angular-cli
  • create-react-app
  • javascript
  • polymer
  • typescript
  • vue

Generate and Embed New Projects#

Creating custom projects on-demand from any data source is super simple with the SDK. There are two methods for doing this:

  • openProject to create a new project & open it in a new tab (or current window).
  • embedProject to create a new project & embed it on the current page.

View live demo on StackBlitz.

sdk.openProject(project[, opts])#

Create a new project and open it in a new tab (or in the current window).

Project Payload#

{  files: {[path: string]: string};  title: string;  description: string;  template: 'angular-cli' | 'create-react-app' | 'typescript' | 'javascript';  tags?: string[];  dependencies?: {[name: string]: string};  settings?: {    compile?: {      trigger?: 'auto' | 'keystroke' | 'save';      action?: 'hmr' | 'refresh';      clearConsole?: boolean;    };  };}

Options#

{  openFile?: string; // Show a specific file on page load  newWindow?: true // Open in new window or in current window  hideDevTools?: boolean; // Hide the debugging console  devToolsHeight?: number; // Set the height of the debugging console  initialPath?: string; // The initial URL path which the preview should open  origin?: string; // Set the origin URL of your StackBlitz EE server}

Required Files for Templates#

angular-cliRequires index.html and main.ts to be present
create-react-appRequires index.html and index.js to be present
typescriptRequires index.html and index.ts to be present
javascriptRequires index.html and index.js to be present

sdk.embedProject(elementOrId, project[, embedOpts])#

Create a new project and embed it on the current page. Returns a promise resolving it's VM instance.

elementOrId: Either an element's ID string or the target HTMLElement itself.

project: The same project payload as the openProject method.

embedOpts: Optional argument that allows you to implement various embed controls:

Embed Options#

{  openFile?: string; // Show a specific file on embed load  clickToLoad?: boolean; // Load editor only when clicked ("click to load")  view?: 'preview' | 'editor';  height?: number | string;  width?: number | string;  hideExplorer?: boolean;  hideNavigation?: boolean;  forceEmbedLayout?: boolean; // Disables the full stackblitz UI on larger screen sizes  initialPath?: string; // The initial URL path the preview should open  origin?: string; // Set the origin URL of your StackBlitz EE server}

Open and Embed Github Repos#

Yup, you can point directly at Github repos containing Angular/React projects and it'll automatically pull them down & run them.

View live demo on StackBlitz.

sdk.openGithubProject(repoSlug[, opts])#

Open a project from Github and open it in a new tab (or in the current window).

repoSlug: String of the Github username, repo and optionally branch/tag/commit.

opts: The same options object as openProject

sdk.embedGithubProject(elementOrId, repoSlug[, embedOpts])#

Embeds a project from Github on the current page. Returns a promise resolving it's VM instance.

elementOrId: Either an element ID string or the target HTMLElement itself.

repoSlug: String of the Github username, repo and optionally branch/tag/commit.

embedOpts: Optional embed options object

Open and Embed StackBlitz Projects#

If you have a specific StackBlitz project ID you want to open or embed, you can use these methods:

sdk.openProjectId(projectId[, opts])#

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

projectId: The ID of the StackBlitz project to open

opts: The same options object as openProject

sdk.embedProjectId(elementOrId, projectId[, embedOpts])#

Embeds an existing StackBlitz project on the current page. Returns a promise resolving it's VM instance.

elementOrId: Either an element ID string or the target HTMLElement itself.

projectId: The ID of the StackBlitz project to open

embedOpts: Optional embed options object

Controlling the VM#

All of the embed methods on the SDK automatically connect to the embedded StackBlitz VM and return a promise containing an initialized VM class. This allows you to have programmatic access of the file system, package manager, editor, and more.

Note: The VM API's are currently under active development—we'd love to hear your feedback.

View live demo on StackBlitz.

vm.applyFsDiff(diff)#

Apply batch updates to the FS in one call. Returns a promise.

diff: A diff object containing files to create and delete.

DIFF OBJECT#

{  create: {    [path: string]: string // path=>contents of files to create  },  destroy: string[] // Paths of files to delete}

vm.getFsSnapshot()#

Get a snapshot of the entire FS. Returns a promise resolving the file system object.

vm.editor.openFile(path)#

Open a file in the editor that exists in the current FS. Returns a promise.

path: String of entire file path (i.e. 'somefolder/index.js')

vm.preview.origin#

String. The URL of the preview domain that the user can open in new tab(s) as they use the embed. Every project created with the embedProject method gets its own unique preview URL.

vm.getDependencies()#

Returns a promise resolving an object containing the currently installed dependencies with corresponding version numbers.