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/sdkOr 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:
| Project Type | Environment |
|---|---|
angular-cli | EngineBlock |
create-react-app | EngineBlock |
javascript | EngineBlock |
polymer | EngineBlock |
typescript | EngineBlock |
vue | EngineBlock |
node | WebContainers |
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:
openProjectto create a new project & open it in a new tab (or current window).embedProjectto create a new project & embed it on the current page.
important
Binary files (such as archives or non-SVG images) are not supported for the dynamically created projects.
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' | 'polymer' | 'vue' | 'node'; dependencies?: {[name: string]: string}; settings?: { compile?: { trigger?: 'auto' | 'keystroke' | 'save'; action?: 'hmr' | 'refresh'; clearConsole?: boolean; }; };}Options#
{ openFile?: string | string[]; // Show one or multiple files 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-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 |
node | no requirements |
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 | string[]; // Show one or multiple files 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.
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#
{ 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.