SDK Options Reference
Project
An object defining the contents and settings of a StackBlitz project.
| Property | Required | Type | Description |
|---|---|---|---|
title | Yes | String | The project title. |
description | Yes | String | A short description for this project. |
template | Yes | ProjectTemplate (String) | Determines how code compiles and runs. |
files | Yes | ProjectFiles (Object) | Project files and their contents. |
dependencies | No | ProjectDependencies (Object) | Specifies npm dependencies (EngineBlock only). |
settings | No | ProjectSettings (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 name | Environment | Required files |
|---|---|---|
'angular-cli' | EngineBlock | index.html and main.ts |
'create-react-app' | EngineBlock | index.html and index.js |
'html' | EngineBlock | index.html |
'javascript' | EngineBlock | index.html and index.js |
'polymer' | EngineBlock | index.html |
'typescript' | EngineBlock | index.html and index.ts |
'vue' | EngineBlock | public/index.html and src/main.js |
'node' | WebContainers | No 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. For WebContainers, please provide a package.json file instead.
Read more about the recommended ways to specify project dependencies for each runtime environment.
ProjectSettings
Compilation settings for EngineBlock projects.
| Property | Type | Description | Default |
|---|---|---|---|
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.clearConsole | Boolean | Determines 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.
| Property | Type | Description | Default Value |
|---|---|---|---|
clickToLoad | Boolean | Shows a UI dialog asking users to run the project. | false |
devToolsHeight | Number | Sets the Console height (from 0 to 100). EngineBlock only. | - |
forceEmbedLayout | Boolean | Whether to use the embed layout or the full editor layout. This option is deprecated and will be removed in a future release. | false |
hideDevTools | Boolean | Hides the Console completely. EngineBlock only. | false |
hideExplorer | Boolean | Hides the ActivityBar. | false |
newWindow | Boolean | Opens the project in a new tab. | true |
openFile | OpenFileOption (String or Array) | Specifies which file(s) to open in the editor and code lines to highlight. | - |
origin | String | StackBlitz Enterprise Edition: sets the origin URL of the StackBlitz EE instance. | - |
showSidebar | Boolean | Shows the Sidebar as open (true) or closed (false) on page load. | - |
terminalHeight | Number | Sets the Terminal height (from 0 to 100). WebContainers only. | 30 |
theme | UiThemeOption (String) | Sets the desired color theme. | see UiThemeOption |
view | UiViewOption (String) | Sets the initial UI view: editor, preview, or both. | see UiThemeOption |
EmbedOptions
Display options available when embedding a project in an iframe.
| Property | Type | Description | Default Value |
|---|---|---|---|
clickToLoad | Boolean | Shows a UI dialog asking users to run the project. | false |
devToolsHeight | Number | Sets Console height (from 0 to 100). EngineBlock only. | - |
forceEmbedLayout | Boolean | Whether to use the embed layout or the full editor layout. This option is deprecated and will be removed in a future release. | true |
height | Number | Sets the height of the embed iframe. | 300 |
hideDevTools | Boolean | Hides the Console completely. EngineBlock only. | false |
hideExplorer | Boolean | Hides the ActivityBar. | false |
hideNavigation | Boolean | Hides the preview URL in embeds. | false |
openFile | OpenFileOption (String or Array) | Specifies which file(s) to open in the editor and code lines to highlight. | - |
origin | String | StackBlitz Enterprise Edition: sets the origin URL of the StackBlitz EE instance. | - |
showSidebar | Boolean | Shows the Sidebar as open (true) or closed (false) on page load. | - |
terminalHeight | Number | Sets Terminal height (from 0 to 100). WebContainers only. | 30 |
theme | UiThemeOption (String) | Sets the desired color theme. | see UiThemeOption |
view | UiViewOption (String) | Sets the initial UI view: editor, preview, or both. | see UiViewOption |
width | Number | Sets 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.
| Value | Description |
|---|---|
'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”).
| Value | Description |
|---|---|
'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) |