COREpolly

Documentation

Welcome to StackBlitz! We’ve created this documentation to help answer any questions you may have about what StackBlitz is, how to use it and what its APIs are.

Just learning about StackBlitz?

Take a look at our announcement post which covers our core functionality, feature set and motivations behind the project.

Curious how our technology works?

We recommend reading the writeup we did and checking out our Github repo.

Embedding

On StackBlitz.com, you can create new projects and get the embed code from the ‘Share’ dropdown link in the top navigation like so:

Then just paste the embed code in an iframe and you’re good to go!

<iframe src="https://stackblitz.com/edit/angular?embed=1"></iframe>

Alternatively, you can also use our Javascript SDK methods for easily embedding StackBlitz projects on the page & avoid all the hassles of creating/configuring iframes.

Embed Options

file File path The default file to have open in the editor
embed 0 / 1 Force embed view regardless of screen size
hideExplorer 0 / 1 Hide file explorer pane in embed view
hideNavigation 0 / 1 Hide the browser navigation UI
ctl 0 / 1 Require user to 'click to load' the embed
view editor / preview Which view to open by default
hidedevtools 0 / 1 Hide the debugging console in the editor preview
devtoolsheight 0 < height < 1000 Set the height of the debugging console in the editor preview

Embed on Medium

In your Medium article, simply take your project URL (i.e. https://stackblitz.com/edit/angular) and paste it. After you hit enter, it should automatically become an embed.

Importing Projects

Upload From Your Computer

With your desired StackBlitz project open, simply drag and drop any files and folder you want to import:

Import from Github

You can run any public repo on Github by providing the username + repo name like so:

stackblitz.com/github/{GH_USERNAME}/{REPO_NAME}

And you can also optionally specify a branch, tag, or commit:

.../github/{GH_USERNAME}/{REPO_NAME}/tree/{TAG|BRANCH|COMMIT}

Automatically stays in sync with your repo

Whenever you push commits to Github, the corresponding StackBlitz project automatically updates with the latest changes — ensuring Github remains your code’s source of truth.

Supported project types

We currently support projects using @angular/cli and create-react-app. Support for Ionic, Vue, and custom webpack configs is coming soon!

StackBlitz API

You can create new StackBlitz projects programmatically from any data source using our POST API or the openProject & embedProject methods in our Javascript SDK.

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:

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>

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:

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
}

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

{
  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
}

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.

POST API

Create new projects by simply POSTing the desired project data from a form— useful when you don’t/can’t use our Javascript SDK.

Required form fields

project[title] = Project title
project[description] = Project description
project[files][FILE_PATH] = Contents of file, specify file path as key
project[files][ANOTHER_FILE_PATH] = Contents of file, specify file path as key
project[dependencies] = JSON string of dependencies field from package.json
project[template] = Can be one of: typescript, angular-cli, create-react-app, javascript

You can also optionally include tags:

project[tags][] = rxjs
project[tags][] = example

Example payload

Below is an example HTML form that generates a project from the RxJS docs using the typescript template:

<html lang="en">
<head></head>
<body>

<form id="mainForm" method="post" action="https://stackblitz.com/run" target="_self">
<input type="hidden" name="project[files][index.ts]" value="import { Observable } from 'rxjs/Observable';
import 'rxjs/add/observable/fromEvent';
import 'rxjs/add/operator/scan';

var button = document.querySelector('button');
Observable.fromEvent(button, 'click')
  .scan((count: number) => count + 1, 0)
  .subscribe(count => console.log(`Clicked ${count} times`));
">
<input type="hidden" name="project[files][index.html]" value="<button>Click Me</button>
">
<input type="hidden" name="project[tags][]" value="rxjs">
<input type="hidden" name="project[tags][]" value="example">
<input type="hidden" name="project[tags][]" value="tutorial">
<input type="hidden" name="project[description]" value="RxJS Example">
<input type="hidden" name="project[dependencies]" value="{&quot;rxjs&quot;:&quot;5.5.6&quot;}">
<input type="hidden" name="project[template]" value="typescript">
<input type="hidden" name="project[settings]" value="{&quot;compile&quot;:{&quot;clearConsole&quot;:false}}">
</form>
<script>document.getElementById("mainForm").submit();</script>

</body></html>