Skip to content

SDK Options Reference

Project

An object defining the contents and settings of a StackBlitz project.

PropertyRequiredTypeDescription
titleYesStringThe project title.
descriptionYesStringA short description for this project.
templateYesProjectTemplate (String)Determines how code compiles and runs.
filesYesProjectFiles (Object)Project files and their contents.
dependenciesNoProjectDependencies (Object)Specifies npm dependencies (EngineBlock only).
settingsNoProjectSettings (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 nameEnvironmentRequired files
'angular-cli'EngineBlockindex.html and main.ts
'create-react-app'EngineBlockindex.html and index.js
'html'EngineBlockindex.html
'javascript'EngineBlockindex.html and index.js
'polymer'EngineBlockindex.html
'typescript'EngineBlockindex.html and index.ts
'vue'EngineBlockpublic/index.html and src/main.js
'node'WebContainersNo 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.

PropertyTypeDescriptionDefault
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.clearConsoleBooleanDetermines 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.

DEMO

Check this demo showcasing all available open options:

PropertyTypeDescriptionDefault Value
clickToLoadBooleanShows a UI dialog asking users to run the project.false
devToolsHeightNumberSets the Console height (from 0 to 100). EngineBlock only.-
forceEmbedLayoutBooleanWhether to use the embed layout or the full editor layout. This option is deprecated and will be removed in a future release.false
hideDevToolsBooleanHides the Console completely. EngineBlock only.false
hideExplorerBooleanHides the ActivityBar.false
newWindowBooleanOpens the project in a new tab.true
openFileOpenFileOption (String or Array)Specifies which file(s) to open in the editor and code lines to highlight.-
originStringStackBlitz Enterprise Edition: sets the origin URL of the StackBlitz EE instance.-
showSidebarBooleanShows the Sidebar as open (true) or closed (false) on page load.-
terminalHeightNumberSets the Terminal height (from 0 to 100). WebContainers only.30
themeUiThemeOption (String)Sets the desired color theme.see UiThemeOption
viewUiViewOption (String)Sets the initial UI view: editor, preview, or both.see UiThemeOption

EmbedOptions

Display options available when embedding a project in an iframe.

DEMO

Check this demo showcasing all available embed options:

PropertyTypeDescriptionDefault Value
clickToLoadBooleanShows a UI dialog asking users to run the project.false
devToolsHeightNumberSets Console height (from 0 to 100). EngineBlock only.-
forceEmbedLayoutBooleanWhether to use the embed layout or the full editor layout. This option is deprecated and will be removed in a future release.true
heightNumberSets the height of the embed iframe.300
hideDevToolsBooleanHides the Console completely. EngineBlock only.false
hideExplorerBooleanHides the ActivityBar.false
hideNavigationBooleanHides the preview URL in embeds.false
openFileOpenFileOption (String or Array)Specifies which file(s) to open in the editor and code lines to highlight.-
originStringStackBlitz Enterprise Edition: sets the origin URL of the StackBlitz EE instance.-
showSidebarBooleanShows the Sidebar as open (true) or closed (false) on page load.-
terminalHeightNumberSets Terminal height (from 0 to 100). WebContainers only.30
themeUiThemeOption (String)Sets the desired color theme.see UiThemeOption
viewUiViewOption (String)Sets the initial UI view: editor, preview, or both.see UiViewOption
widthNumberSets 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.

DEMO

Check this demo showcasing all available open file options:

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:

js
  // Opens a single file
  openFile: 'src/App.tsx',

Example with a single file with third line highlighted:

js
  // 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:

js
  // Opens a single file and highlights a range
  openFile: 'src/App.tsx:L5-L8',

Example with three editor tabs (the last file is displayed):

js
  // 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:

js
  // 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:

js
  // 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.

ValueDescription
'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”).
ValueDescription
'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)