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 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:
Or add a script tag to the UMD build on jsDelivr/Unpkg — the SDK will be available on window as StackBlitzSDK
:
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.
sdk.openProject(project[, opts])
Create a new project and open it in a new tab (or in the current window).
Project payload
Options
Required files for templates
angular-cli | Requires index.html and main.ts to be present |
create-react-app | Requires index.html and index.js to be present |
typescript | Requires index.html and index.ts to be present |
javascript | Requires 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
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.
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.
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
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.