StackBlitz

https://github.com/stackblitz/docs
Admin
StackBlitz is an instant fullstack web IDE for the JavaScript ecosystem powered by WebContainers,...
Tokens:68,818
Snippets:606
Trust Score:9.5
Update:1 week ago
Show doc for...
Tokens:
Raw
### Run the docs site locally with npm install and npm start

Source: https://github.com/stackblitz/docs/blob/main/README.md

Use these commands after cloning the repository to start the development server. Run them in the project root.

```sh
npm install
npm start
```

--------------------------------

### Configure project with package.json and .stackblitzrc

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/webcontainers/project-config.md

Two JSON configuration examples for WebContainers projects. The first shows the `stackblitz` field in `package.json` to set a custom start command. The second shows an alternative `.stackblitzrc` file that disables dependency installation and sets environment variables.

```json
{
  "name": "lib-example",
  "version": "1.0.0",
  "license": "MIT",
  /// ...
  "stackblitz": {
    "startCommand": "npm start"
  }
}
```

```json
{
  "installDependencies": false,
  "startCommand": "my-custom-command",
  "env": {
    "NODE_ENV": "development"
  }
}
```

--------------------------------

### Admin Console Installation Prompts

Source: https://github.com/stackblitz/docs/blob/main/docs/enterprise/installation/quickstart-existing-cluster.md

Example output shown during installation. You will be prompted to enter the namespace and set a password for the Admin Console.

```sh
Enter the namespace to deploy to: stackblitz
 • Deploying Admin Console
    • Creating namespace ✓
    • Waiting for datastore to be ready ✓
Enter a new password to be used for the Admin Console:
```

--------------------------------

### Using npm commands with Turbo

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/webcontainers/turbo-package-manager.md

Shows common npm commands that work with Turbo in WebContainers. Includes installing dependencies, adding a dependency, and running a start script.

```sh
# install dependencies
npm install

# add a dependency
npm install lodash

# run `start` script
npm start
```

--------------------------------

### Get VM with connect method

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/api/javascript-sdk-vm.md

Use the connect method to retrieve the VM instance for an existing StackBlitz iframe. The example shows how to embed a project and then connect to it when a button is clicked.

```javascript
import sdk from '@stackblitz/sdk';

const EMBED_ID = 'embed';

// Embeds iframe
sdk.embedProjectId(EMBED_ID, 'react-ts');

// Retrieves and uses the VM when clicking a button
document.getElementById('test-button').addEventListener('click', async () => {
  const iframe = document.getElementById(EMBED_ID);
  const vm = await sdk.connect(iframe);
  const deps = await vm.getDependencies();
  console.log(deps);
});
```

--------------------------------

### package.json scripts for dev server

Source: https://github.com/stackblitz/docs/blob/main/docs/guides/integration/open-from-github.md

Example package.json scripts that define a `dev` script to launch a development server. StackBlitz looks for `dev` or `start` by default.

```json
{
  "scripts": {
    "build": "vite build",
    "dev": "vite"
  }
}
```

--------------------------------

### Turbo install with missing polyfill version warning

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/webcontainers/turbo-package-manager.md

Example output when a requested version of a package is missing and Turbo installs the original package instead, reporting a warning.

```text
❯ turbo
┌ [1/3] 🔍  Resolving dependencies
└ Completed in 0.629s
┌ [2/3] 🚚  Fetching dependencies
│ warn applyPolyfills esbuild requires a polyfill but no matching version was found for 0.13.8.
└ Completed in 1.044s
┌ [3/3] 🔗  Linking dependencies
└ Completed in 0.068s

success Saved lockfile "package-lock.json"
success Updated "package.json"

success Install finished in 2.132s
```

--------------------------------

### Get VM with embedProjectId and applyFsDiff

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/api/javascript-sdk-vm.md

Use the embedProjectId method to embed a project and get the VM instance. The example shows how to get dependencies and apply a filesystem diff to create new files.

```javascript
import sdk from '@stackblitz/sdk';

async function start() {
  // Embeds a project and keeps track of the VM
  const vm = await sdk.embedProjectId('embed', 'react-ts');

  // Performs an action with VM
  const deps = await vm.getDependencies();
  await vm.applyFsDiff({
    create: {
      'hello.txt': 'Hello, this is a new file!',
      'deps.txt': JSON.stringify(deps, null, 2),
    },
    destroy: [],
  });
}

start();
```

--------------------------------

### openProject example

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/api/javascript-sdk.md

Creates a new project and opens it in a new tab or the current window. The example shows a JavaScript starter project with files and settings. Note that new projects are not persisted on StackBlitz unless forked.

```javascript
sdk.openProject(
  {
    title: 'JS Starter',
    description: 'Blank starter project for building ES6 apps.',
    template: 'javascript',
    files: {
      'index.html': `<div id="app"></div>`,
      'index.js': `import './style.css';
const appDiv = document.getElementById('app');
appDiv.innerHTML = '<h1>JS Starter</h1>';`,
      'style.css': `body { font-family: system-ui, sans-serif; }`,
    },
    settings: {
      compile: {
        trigger: 'auto',
        clearConsole: false,
      },
    },
  },
  {
    newWindow: false,
    openFile: ['index.js', 'index.html,style.css'],
  },
);
```

--------------------------------

### Turbo install with polyfill replacement log

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/webcontainers/turbo-package-manager.md

Example output when Turbo replaces non-supported packages with polyfills. Shows the explicit log message and the replacement of esbuild with esbuild-wasm.

```text
❯ turbo
┌ [1/3] 🔍  Resolving dependencies
└ Completed in 0.629s
┌ [2/3] 🚚  Fetching dependencies
└ Completed in 1.044s
┌ [3/3] 🔗  Linking dependencies
└ Completed in 0.068s
info Some packages were automatically replaced with polyfills.
For more information see https://turbo.sh/polyfills.
└─ esbuild@0.8.57 => esbuild-wasm@0.8.57

success Install finished in 2.468s
```

--------------------------------

### Install with license and airgap bundle via CLI

Source: https://github.com/stackblitz/docs/blob/main/docs/enterprise/installation/air-gapped-installs.md

Completes installation using the CLI with license and airgap bundle. Add --disable-image-push if images already uploaded.

```sh
kubectl kots install app-name \
  [--disable-image-push \]
  --namespace app-name \
  --license-file ./license.yaml \
  --config-values ./configvalues.yaml \
  --airgap-bundle /path/to/application.airgap \
  --kotsadm-registry your.registry.host \
  --kotsadm-namespace your-stackblitz-namespace \
  --registry-username rw-username \
  --registry-password rw-password
```

--------------------------------

### Install the StackBlitz addon with pnpm

Source: https://github.com/stackblitz/docs/blob/main/docs/guides/integration/storybook-addon.md

Install the addon as a dev dependency using pnpm.

```bash
pnpm add --save-dev @stackblitz/storybook-addon-stackblitz
```

--------------------------------

### Install Admin Console with registry details

Source: https://github.com/stackblitz/docs/blob/main/docs/enterprise/installation/air-gapped-installs.md

Installs the Admin Console to your cluster, providing registry details. Prompts for a namespace and admin console password.

```sh
kubectl kots install --kotsadm-registry your.registry.hostname \
  --kotsadm-namespace your-stackblitz-namespace \
  --registry-username readonly-username \
  --registry-password readonly-password \
  stackblitz
```

--------------------------------

### Install StackBlitz SDK via npm

Source: https://github.com/stackblitz/docs/blob/main/docs/guides/integration/create-with-sdk.md

Run this command in the terminal to install the @stackblitz/sdk package.

```bash
npm install @stackblitz/sdk
```

--------------------------------

### Dependencies entry example

Source: https://github.com/stackblitz/docs/blob/main/docs/guides/integration/create-with-sdk.md

Example of the dependencies object, listing libraries and their versions, similar to a package.json file.

```javascript
{
  dependencies: {
    lodash: "3.8",
    react: "17"
  }
}
```

--------------------------------

### Install the StackBlitz addon with npm

Source: https://github.com/stackblitz/docs/blob/main/docs/guides/integration/storybook-addon.md

Install the addon as a dev dependency using npm.

```bash
npm install @stackblitz/storybook-addon-stackblitz --save-dev
```

--------------------------------

### .stackblitzrc startCommand option

Source: https://github.com/stackblitz/docs/blob/main/docs/guides/integration/open-from-github.md

Configuration file option to set a custom start command.

```json
{
  "startCommand": "npm run build"
}
```

--------------------------------

### Open project demo with SDK

Source: https://github.com/stackblitz/docs/blob/main/docs/guides/integration/create-with-sdk.md

This example shows how to use the SDK's openProject method to create a project with files, a template, title, and description, and open it in a new window.

```javascript
sdk.openProject(
  {
    files: {
      'index.html': `<h1>Hello world!</h1>`,
      'index.js': `alert('Woohoo! We can start documenting!')`,
    },
    template: 'javascript',
    title: `My First Docs!`,
    description: `This is an example of my first doc!`,
  },
  {
    newWindow: true,
  }
);
```

--------------------------------

### Install the StackBlitz addon with yarn

Source: https://github.com/stackblitz/docs/blob/main/docs/guides/integration/storybook-addon.md

Install the addon as a dev dependency using yarn.

```bash
yarn add --dev @stackblitz/storybook-addon-stackblitz
```

--------------------------------

### Install Kots CLI

Source: https://github.com/stackblitz/docs/blob/main/docs/enterprise/installation/air-gapped-installs.md

Run this command on a workstation with kubectl access to install the Kots CLI if it is not already installed.

```sh
curl https://kots.io/install | bash
```

--------------------------------

### Install StackBlitz Admin Console

Source: https://github.com/stackblitz/docs/blob/main/docs/enterprise/installation/quickstart-existing-cluster.md

Run this command to install the Admin Console for StackBlitz. You will be prompted for a namespace (default: stackblitz) and a password for the Admin Console.

```sh
kubectl kots install stackblitz
```

--------------------------------

### Install StackBlitz Enterprise on existing cluster

Source: https://github.com/stackblitz/docs/blob/main/docs/enterprise/installation/administrator-guide.md

Run these commands from a workstation with kubectl access to the cluster. The first installs the kots plugin, the second installs the StackBlitz admin console and sets up a port forward to access it at http://localhost:8800.

```sh
 curl https://kots.io/install | bash
 kubectl kots install stackblitz
```

--------------------------------

### Run the KOTS installer on GCP

Source: https://github.com/stackblitz/docs/blob/main/docs/enterprise/installation/quickstart-gcp.md

Run this command on a GCP instance to install StackBlitz Enterprise with the embedded Kubernetes distribution. The installer may prompt for manual package installation; see the Host Package Requirements link.

```sh
curl -sSL https://k8s.kurl.sh/stackblitz | sudo bash
```

--------------------------------

### Example output when using yarn with node-sass

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/webcontainers/turbo-package-manager.md

Shows the terminal output when running yarn with node-sass in the dependency graph. It includes warnings about the deprecation and exclusion, and the successful installation.

```text
❯ yarn
warn preInstall No description field
warn preInstall No repository field
┌ [1/3] 🔍  Resolving dependencies
│ warn deprecation "node-sass" is deprecated and excluded from installation. It only receives maintenance
│ releases and there are no plans to add additional features or compatibility with any new CSS or SASS features.
│ It's recommended to migrate to "sass". Check out migration guide https://turbo.sh/node-sass.
└ Completed in 4.366s
┌ [2/3] 🚚  Fetching dependencies
│ info pruneDeps Excluding 1 dependency. For more information use `--verbose`.
└ Completed in 1.06s
┌ [3/3] 🔗  Linking dependencies
└ Completed in 0.066s

success Saved lockfile "package-lock.json"
success Updated "package.json"

success Install finished in 5.551s
```

--------------------------------

### Use startScript URL parameter

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/webcontainers/project-config.md

URL examples using the `startScript` parameter. The first runs a single script on project load; the second runs multiple scripts sequentially using comma-separated values. The `startScript` parameter only accepts existing keys from the `scripts` field in `package.json`.

```text
https://stackblitz.com/edit/project-id?startScript=test
```

```text
https://stackblitz.com/edit/project-id?startScript=build,serve
```

--------------------------------

### Get preview URL with preview.getUrl()

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/api/javascript-sdk-vm.md

Asynchronously gets the current preview URL and checks if it starts with '/about'. The URL may not reflect the exact path if navigation occurred inside the iframe. In WebContainers, returns null until a web server starts.

```javascript
const url = await vm.preview.getUrl();

if (url != null && url.startsWith('/about')) {
  console.log('Looks like the About page!');
}
```

--------------------------------

### Admin Console Ready Screen

Source: https://github.com/stackblitz/docs/blob/main/docs/enterprise/installation/quickstart-existing-cluster.md

Example output after the Admin Console is ready. It indicates that you can press Ctrl+C to exit and access the Admin Console at http://localhost:8800.

```sh
  • Waiting for Admin Console to be ready ✓

  • Press Ctrl+C to exit
  • Go to http://localhost:8800 to access the Admin Console
```

--------------------------------

### Installation output with password and Kotsadm URL

Source: https://github.com/stackblitz/docs/blob/main/docs/enterprise/installation/quickstart-gcp.md

After installation, the terminal output shows the generated password and the Kotsadm URL. Copy the password; it is required for accessing the Admin Console and won't be shown again.

```sh
Login with password (will not be shown again): xyzabc123
Kotsadm: http://34.184.141.48:8800
```

--------------------------------

### embedProject example

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/api/javascript-sdk.md

Creates a new project and embeds it in the current page, returning a promise resolving to a VM instance. The example shows a Node.js project with files and embed options.

```javascript
sdk.embedProject(
  'embed',
  {
    title: 'Node Starter',
    description: 'A basic Node.js project',
    template: 'node',
    files: {
      'index.js': `console.log('Hello World!');`,
      'package.json': `{
      "name": "my-project",
      "scripts": { "hello": "node index.js", "start": "serve node_modules" },
      "dependencies": { "serve": "^14.0.0" },
      "stackblitz": { "installDependencies": true, "startCommand": "npm start" },
    }`,
    },
  },
  {
    clickToLoad: true,
    openFile: 'index.js',
    terminalHeight: 50,
  },
);
```

--------------------------------

### getFsSnapshot: Get filesystem snapshot

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/api/javascript-sdk-vm.md

Gets a snapshot of all project files and their content as an object.

```javascript
const files = await vm.getFsSnapshot();
console.log(files); // { 'index.js': '…', 'package.json': '…', … }
```

--------------------------------

### openGithubProject: Open a GitHub repository in StackBlitz

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/api/javascript-sdk.md

Opens a project from GitHub in StackBlitz. The first example opens the repository in the current tab (newWindow: false). The second example opens a specific sub-folder of the 'main' branch in a new tab.

```javascript
// Imports https://github.com/username/repository-name to StackBlitz,
// and opens the resulting StackBlitz project in the current tab
sdk.openGithubProject('username/repository-name', {
  newWindow: false,
});

// Imports the 'examples/getting-started' sub-folder of the 'main' branch of
// the https://github.com/username/repository-name repository to StackBlitz,
// and opens the resulting StackBlitz project in a new tab
sdk.openGithubProject('username/repository-name/tree/main/examples/getting-started');
```

--------------------------------

### Load the SDK as a UMD bundle

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/api/javascript-sdk.md

Load the UMD bundle from UNPKG, which adds a global window.StackBlitzSDK object. The example shows calling StackBlitzSDK.embedProject with a placeholder argument.

```html
<script src="https://unpkg.com/@stackblitz/sdk@1/bundles/sdk.umd.js"></script>
<script>
  StackBlitzSDK.embedProject(/* … */);
</script>
```

--------------------------------

### WebContainers: Provide dependencies in package.json

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/api/javascript-sdk-dependencies.md

For WebContainers projects (template: 'node'), npm installs dependencies from the project's package.json. This example shows how to define a package.json file and pass it in the project files, ignoring the project.dependencies option.

```javascript
import sdk from '@stackblitz/sdk';

const packageJson = `{
  "name": "node-starter",
  "version": "0.0.0",
  "scripts": {
    "start": "serve public"
  },
  "dependencies": {
    "serve": "^14.0.0"
  }
}`;

const project = {
  title: 'Node serve demo',
  description: 'Node.js server demo using the "serve" package',
  template: 'node',
  files: {
    'package.json': packageJson,
    'public/index.html': '<h1>Hello world!</h1>',
  },
};

sdk.openProject(project);
```

--------------------------------

### DNS A records for StackBlitz instance

Source: https://github.com/stackblitz/docs/blob/main/docs/enterprise/configuring-dns.md

Set these DNS A records to point the root domain and wildcard subdomain to the instance IP (172.16.4.20 in this example).

```text
A stackblitz.example.com 172.16.4.20
A *.stackblitz.example.com 172.16.4.20
```

--------------------------------

### Open a StackBlitz project with sdk.openProjectId

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/api/javascript-sdk.md

Opens an existing StackBlitz project in a new tab or current window. The example opens 'my-cool-project' in the current window with the Preview pane hidden, using the openFile and view options.

```javascript
// Opens https://stackblitz.com/edit/my-cool-project in the current window
// with the Preview pane hidden
sdk.openProjectId('my-cool-project', {
  newWindow: false,
  openFile: 'src/App.tsx',
  view: 'editor',
});
```

--------------------------------

### connect(iframe)

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/api/javascript-sdk-vm.md

Retrieves the VM instance for an existing StackBlitz iframe. Use this method to get programmatic access to an already embedded project.

```APIDOC
## connect(iframe)

### Description
Retrieves the VM instance for an existing StackBlitz iframe. Use this method to get programmatic access to an already embedded project.

### Method
connect

### Parameters
- **iframe** (HTMLIframeElement) - Required - An iframe embedding a StackBlitz project.

### Returns
- **Promise<VM>** - A Promise that resolves to a VM instance for the embedded project.

### Example
```js
import sdk from '@stackblitz/sdk';

const EMBED_ID = 'embed';

// Embeds iframe
sdk.embedProjectId(EMBED_ID, 'react-ts');

// Retrieves and uses the VM when clicking a button
document.getElementById('test-button').addEventListener('click', async () => {
  const iframe = document.getElementById(EMBED_ID);
  const vm = await sdk.connect(iframe);
  const deps = await vm.getDependencies();
  console.log(deps);
});
```
```

--------------------------------

### Load the SDK as an ES module from UNPKG

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/api/javascript-sdk.md

Load the SDK directly in an HTML page using a module script from UNPKG. The example shows calling sdk.embedProject with a placeholder argument.

```html
<script type="module">
  import sdk from 'https://unpkg.com/@stackblitz/sdk@1/bundles/sdk.m.js';
  sdk.embedProject(/* … */);
</script>
```

--------------------------------

### OpenFileOption

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/api/javascript-sdk-options.md

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 line highlighting using the format {path}:L{start} or {path}:L{start}-L{end}.

```APIDOC
## OpenFileOption

### Description
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.

### Type
- `string | string[]` - Required - A single file path or an array of file path strings. Each string can be a comma-separated list of file paths.

### Usage Examples

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

#### Single file with a highlighted line
```js
// Opens a single file and highlights the third line
openFile: 'src/App.tsx:L3',
```

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

#### Multiple tabs (last file displayed)
```js
// Opens three editor tabs with the last file displayed
openFile: 'index.html,package.json,src/App.tsx',
```

#### Multiple panes (one tab per pane)
```js
// Opens three side-by-side editor panes with one tab in each pane
openFile: ['index.html', 'package.json', 'src/App.tsx'],
```

#### Multiple panes (multiple tabs per pane)
```js
// Opens two editor panes with two tabs in each pane
openFile: ['index.html,package.json', 'src/App.tsx,src/App.css'],
```

```

--------------------------------

### Title and description properties

Source: https://github.com/stackblitz/docs/blob/main/docs/guides/integration/create-with-sdk.md

Example of the title and description properties in the payload, which provide user-facing information when the project opens.

```javascript
{
  title: `My First Docs!`,
  description: `This is an example of my first doc!`
}
```

--------------------------------

### console.log in details container

Source: https://github.com/stackblitz/docs/blob/main/docs/playground/test-page.md

A simple JavaScript example inside a details container. Use this to test how code blocks render inside collapsible details.

```js
console.log('Hello, VitePress!')
```

--------------------------------

### Template property example

Source: https://github.com/stackblitz/docs/blob/main/docs/guides/integration/create-with-sdk.md

Shows the template property set to 'javascript', which defines how the StackBlitz environment will build the project.

```javascript
{
  template: 'javascript'
}
```

--------------------------------

### HTML form POSTing to StackBlitz

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/api/post-api.md

Example HTML form that generates a project from the RxJS docs using the typescript template. Posts to https://stackblitz.com/run with method POST.

```html
<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/of';
import 'rxjs/add/operator/map';

const greeting = 'Hello World!';
const output = document.getElementById('output');
const rxjsLogo = document.createElement('img');
rxjsLogo.src = 'https://stackblitz.com/assets/images/rxjs.svg';
rxjsLogo.width = 100;
rxjsLogo.height = 100;

rxjsLogo.id = 'logo';
output.appendChild(rxjsLogo);

const banner = document.createElement('div');
banner.id = 'banner';
banner.innerHTML = '<h1>' + greeting + '</h1>'; 

output.appendChild(banner);

const link = document.createElement('a');
link.setAttribute('href', 'https://reactivex.io/rxjs/');
link.setAttribute('target', '_blank');
link.textContent = 'RxJS';
output.appendChild(link);

const badge = document.createElement('div');
badge.setAttribute('class', 'badge');
badge.textContent = 'StackBlitz';
output.appendChild(badge);

const badgeStyle = document.createElement('style');
badgeStyle.textContent = '.badge { position: fixed; bottom: 5px; padding: 0 10px; border-radius: 5px; background: #EBEBEB; color: #333; font-size: 14px; line-height: 30px; }';badgeStyle.textContent += '.badge i { font-style: normal; padding-bottom: 3px; }';badgeStyle.textContent += '.badge i { font-style: normal; padding-bottom: 3px; }';badgeStyle.textContent += 'svg { position: fixed; bottom: 0; right: 0; width: 80px; }';document.body.appendChild(badgeStyle);
```

--------------------------------

### Turbo configuration options in .turborc.json

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/webcontainers/turbo-package-manager.md

Example of a .turborc.json file with available options: loglevel, progress, and disablePolyfills. The file is read and merged in a cascading fashion from global and current folder configs.

```js
{
  // the default log level for the CLI
  "loglevel": "info",

  // whether to show progress indicators
  "progress": true,

  //detect the usage of non-supported packages at installation time and swap them
  "disablePolyfills": true
}
```

--------------------------------

### Open a single file with third line highlighted

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/api/javascript-sdk-options.md

Uses the {path}:L{start} format to highlight a single line. Any file change removes the highlight.

```javascript
  // Opens a single file and highlights the third line
  openFile: 'src/App.tsx:L3',
```

--------------------------------

### Open a single file with a range highlighted

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/api/javascript-sdk-options.md

Uses the {path}:L{start}-L{end} format to highlight a range of lines. Any file change removes the highlight.

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

--------------------------------

### getFsSnapshot()

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/api/javascript-sdk-vm.md

Gets a snapshot of the project files and their content. Returns a promise resolving to a ProjectFiles object.

```APIDOC
## getFsSnapshot()

### Description
Gets a snapshot of the project files and their content. Returns a promise resolving to a [ProjectFiles][] object.

### Method
`vm.getFsSnapshot()`

### Parameters
None.

### Request Example
```js
const files = await vm.getFsSnapshot();
console.log(files); // { 'index.js': '…', 'package.json': '…', … }
```

### Response
Returns a promise resolving to a [ProjectFiles][] object.
```

--------------------------------

### Files object with nested folder

Source: https://github.com/stackblitz/docs/blob/main/docs/guides/integration/create-with-sdk.md

Example of the files object with a readme.md file and a src/index.js file inside a src folder. Demonstrates how to specify file paths and contents.

```javascript
{
  files: {
    `readme.md`: `# Welcome to the demo`,
    `src/index.js`: `console.log('Hello, demo!')`
  }
}
```

--------------------------------

### Markdown button for Open in StackBlitz

Source: https://github.com/stackblitz/docs/blob/main/docs/guides/integration/open-from-github.md

Use this Markdown snippet to display an 'Open in StackBlitz' button in a Markdown file. Replace the last URL with your example's path.

```markdown
[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/___YOUR_PATH___)
```

--------------------------------

### Set preview URL with preview.setUrl()

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/api/javascript-sdk-vm.md

Navigates the preview to the '/about' path. The path must start with '/' and cannot change the origin. In WebContainers, the call is ignored if no web server is running.

```javascript
// Navigates to the About page
await vm.preview.setUrl('/about');
```

--------------------------------

### Vue component with highlighted lines

Source: https://github.com/stackblitz/docs/blob/main/docs/playground/test-page.md

A Vue component example with line highlighting (lines 1, 4, 6-8). Demonstrates VitePress code highlighting feature.

```js
export default { // Highlighted
  data () {
    return {
      msg: `Highlighted!
      This line isn't highlighted,
      but this and the next 2 are.`,
      motd: 'VitePress is awesome',
      lorem: 'ipsum'
    }
  }
}
```

--------------------------------

### HTML button for Open in StackBlitz

Source: https://github.com/stackblitz/docs/blob/main/docs/guides/integration/open-from-github.md

Use this HTML snippet to display an 'Open in StackBlitz' button in HTML markup. Replace the href URL with your example's path.

```html
<a href="https://stackblitz.com/github/___YOUR_PATH___">
  <img
    alt="Open in StackBlitz"
    src="https://developer.stackblitz.com/img/open_in_stackblitz.svg"
  />
</a>
```

--------------------------------

### Import the SDK in a JavaScript module

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/api/javascript-sdk.md

Import the SDK as a default export when using a bundler like webpack or Vite. The example shows calling sdk.embedProject with a placeholder argument.

```js
import sdk from '@stackblitz/sdk';
sdk.embedProject(/* … */);
```

--------------------------------

### EngineBlock: Dependencies plus package.json

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/api/javascript-sdk-dependencies.md

For EngineBlock projects, dependencies are specified via the project.dependencies option. This example defines a package.json object, uses its dependencies for project.dependencies, and includes a package.json file in the project files.

```javascript
import sdk from '@stackblitz/sdk';

const PACKAGE_JSON = {
  name: 'cool-project',
  version: '0.0.0',
  private: true,
  dependencies: {
    gsap: '^3.11.0',
    jquery: '^3.6.0',
    lodash: '^4.17.21',
  },
};

const project = {
  title: 'My cool project',
  description: 'Example animation project',
  template: 'javascript',
  // REQUIRED: specify dependencies
  dependencies: PACKAGE_JSON.dependencies,
  files: {
    // Recommended: provide a package.json file with the same dependencies
    'package.json': JSON.stringify(PACKAGE_JSON, null, 2),
    'index.html': '<h1>Hello world!</h1>',
    'index.js': 'import gsap from "gsap";\n// etc.',
  },
};

sdk.openProject(project);
```

--------------------------------

### preview.origin

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/api/javascript-sdk-vm.md

A string with the origin (protocol and domain) of the preview iframe. Every project created with the embedProject method gets a unique preview URL. It is null in WebContainers projects.

```APIDOC
## preview.origin

### Description
A string with the origin (protocol and domain) of the preview iframe. Every project created with the `embedProject` method gets a unique preview URL. Because it is unknown ahead of time if the project will run a web server (and if so, on which port), `vm.preview.origin` will always be `null` in projects running on WebContainers. Use `vm.preview.getUrl()` instead.

### Property
`preview.origin` (string | null)

### Example
```js
if (vm.preview.origin) {
  console.log('Preview is running at ' + vm.preview.origin);
}
```
```

--------------------------------

### editor.openFile: Open files in tabs or split panes

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/api/javascript-sdk-vm.md

Opens one or more files in the editor. Accepts a string or an array of strings. The example shows opening a single file and opening two files in split panes.

```javascript
// opens a single file
await vm.editor.openFile('src/App.css');

// opens two editor panes
await vm.editor.openFile(['README.md', 'index.js']);
```

--------------------------------

### Get encryption key via KOTS CLI

Source: https://github.com/stackblitz/docs/blob/main/docs/enterprise/data-migration.md

Use this command to retrieve the encryption key configuration from your existing StackBlitz deployment. Replace the namespace and sequence number. The output includes stackblitz_enc_key_settings, stackblitz_enc_key, and optionally stackblitz_enc_custom_key.

```sh
kubectl kots get config -n <your stackblitz namespace> --sequence <current release sequence number> --appslug stackblitz | grep -A1 'stackblitz_enc'
```

--------------------------------

### Embed a StackBlitz project with sdk.embedProjectId

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/api/javascript-sdk.md

Embeds an existing StackBlitz project in the specified HTML element on the current page. The example replaces the element with id 'embed' with an iframe of 'my-cool-project', using the openFile option to open multiple files.

```javascript
// Replaces the HTML element with the id of "embed"
// with https://stackblitz.com/edit/my-cool-project embedded in an iframe,
sdk.embedProjectId('embed', 'my-cool-project', {
  openFile: 'index.ts,src/App.tsx',
});
```

--------------------------------

### preview.setUrl(path)

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/api/javascript-sdk-vm.md

Changes the path of the preview URL. Returns a promise resolving to null. The provided path must start with '/' and cannot change the origin of the preview URL. In WebContainers projects, calls will be ignored if there is no web server running currently.

```APIDOC
## preview.setUrl(path)

### Description
Changes the path of the preview URL. Returns a promise resolving to `null`. The provided path must start with `/` and cannot change the origin of the preview URL. In WebContainers projects, calls to `vm.preview.setUrl` will be ignored if there is no web server running currently.

### Method
`preview.setUrl(path)`

### Parameters
- **path** (String) - Required - A URL path starting with `/`.

### Returns
Promise<null>

### Example
```js
// Navigates to the About page
await vm.preview.setUrl('/about');
```
```

--------------------------------

### Embed StackBlitz project on DEV using liquid tag

Source: https://github.com/stackblitz/docs/blob/main/docs/guides/integration/embedding.md

Use the DEV liquid tag with your project URL to embed a StackBlitz project in a DEV post. The example uses a Vite project URL with a specific file open.

```liquid
{% stackblitz https://stackblitz.com/edit/vitejs-vite-y8mdxg?file=index.html %}
```

--------------------------------

### Open a new project with StackBlitzSDK.openProject

Source: https://github.com/stackblitz/docs/blob/main/docs/guides/integration/create-with-sdk.md

Creates a new project with an index.html and index.js file, using the 'javascript' template, and opens it in a new window. The payload includes files, template, title, and description; the options object sets newWindow to true.

```javascript
StackBlitzSDK.openProject(
  // Payload
  {
    files: {
      'index.html': `<h1>Hello world!</h1>`,
      'index.js': `alert('Woohoo! We can start documenting!')`,
    },
    template: 'javascript',
    title: `My First Docs!`,
    description: `This is an example of my first doc!`,
  },

  // Options
  {
    newWindow: true
  }
);
```

--------------------------------

### Import/restore PostgreSQL database with psql

Source: https://github.com/stackblitz/docs/blob/main/docs/enterprise/data-migration.md

Run this command from the directory containing stackblitz_dump.sql.gz to restore the database to a managed PostgreSQL instance. It copies the dump into the pod, then pipes it to psql. Replace placeholders for the managed DB hostname, username, and optional port. The restore drops and recreates the stackblitz_production database if it exists.

```bash
K8S_NAMESPACE=<your stackbltiz namespace> \
PG_POD=$(kubectl get pods -o name -n $K8S_NAMESPACE | grep 'postgres' | grep -v 'kots' | cut -d'/' -f2) && \
kubectl cp stackblitz_dump.sql.gz $K8S_NAMESPACE/$PG_POD:/var/lib/postgresql/data/stackblitz_dump.sql.gz && \
kubectl exec -n $K8S_NAMESPACE -it $PG_POD -- sh -c \
'zcat /var/lib/postgresql/data/stackblitz_dump.sql.gz | \
psql \
-h <managed DB hostname> \
-U <managed DB username>
-p <managed DB port (optional, 5432 by default)> \
-d postgres'
```

--------------------------------

### openProject(project, openOptions)

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/api/javascript-sdk.md

Creates a new project and opens it in a new tab or in the current window. Accepts project data and optional display options.

```APIDOC
## openProject(project, openOptions)

### Description
Creates a new project and opens it in a new tab (or in the current window).

### Method
SDK Method

### Signature
`openProject(project, openOptions)`

### Parameters
- **project** (Project Object) - Required - Project data and settings.
- **openOptions** (OpenOptions Object) - Optional - Display options for the StackBlitz editor.

### Request Example
```js
sdk.openProject(
  {
    title: 'JS Starter',
    description: 'Blank starter project for building ES6 apps.',
    template: 'javascript',
    files: {
      'index.html': `<div id="app"></div>`,
      'index.js': `import './style.css';
const appDiv = document.getElementById('app');
appDiv.innerHTML = '<h1>JS Starter</h1>';`,
      'style.css': `body { font-family: system-ui, sans-serif; }`,
    },
    settings: {
      compile: {
        trigger: 'auto',
        clearConsole: false,
      },
    },
  },
  {
    newWindow: false,
    openFile: ['index.js', 'index.html,style.css'],
  },
);
```

### Response
No explicit response is documented. The method opens a new project in a tab or window.
```

--------------------------------

### newWindow option

Source: https://github.com/stackblitz/docs/blob/main/docs/guides/integration/create-with-sdk.md

By default, the project opens in a new browser window. Set to false to open in the same window.

```javascript
{
  newWindow: false
}
```

--------------------------------

### initialPath option

Source: https://github.com/stackblitz/docs/blob/main/docs/guides/integration/create-with-sdk.md

Sets the path to be opened by the preview window.

```javascript
{
  initialPath: '/posts'
}
```

--------------------------------

### getDependencies()

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/api/javascript-sdk-vm.md

Gets the project's defined dependencies. Returns a promise resolving to a ProjectDependencies object.

```APIDOC
## getDependencies()

### Description
Gets the project's defined dependencies. Returns a promise resolving to a [ProjectDependencies][] object.

### Method
`vm.getDependencies()`

### Parameters
None.

### Behavior
- In EngineBlock projects, returns dependencies as resolved by the built-in package manager, with exact versions as values (e.g., `{ 'react': '18.2.0' }`).
- Since 1.7.0: in projects running on WebContainers, reads the top-level `package.json` and returns an object merging `dependencies` and `devDependencies`, with original version specifiers (e.g., `{ 'react': '^18.0.0' }`).

### Request Example
```js
const deps = await vm.getDependencies();

if (typeof deps['vue'] === 'string') {
  console.log('Looks like a Vue.js project');
}
```

### Response
Returns a promise resolving to a [ProjectDependencies][] object.
```

--------------------------------

### Upgrade with new airgap bundle via CLI

Source: https://github.com/stackblitz/docs/blob/main/docs/enterprise/installation/air-gapped-installs.md

Extracts a new bundle to your registry and uploads the release to Admin Console. Optionally add --deploy to deploy automatically.

```sh
kubectl kots upstream upgrade stackblitz \
  --airgap-bundle StackBlitz.airgap \
  --kotsadm-namespace <registry namespace> \
  --kotsadm-registry <registry host> \
  --registry-username <username> \
  --registry-password <password> \
  -n <admin console namespace>
```

--------------------------------

### POST /run

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/api/post-api.md

Creates a new project by POSTing form data to the StackBlitz run endpoint. This method is useful when you don't or can't use the JavaScript SDK.

```APIDOC
## POST /run

### Description
Creates a new project by POSTing form data to the StackBlitz run endpoint. This method is useful when you don't or can't use the JavaScript SDK.

### Method
POST

### Endpoint
https://stackblitz.com/run

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

### Request Example
```html
<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[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>
```

### Response
#### Success Response
No explicit response schema is documented. The request is expected to create a project and redirect the user to the created project.

### Error Handling
Binary files (such as archives or non-SVG images) are not supported for the dynamically created projects.
```

--------------------------------

### openGithubProject(repoPath, openOptions)

Source: https://github.com/stackblitz/docs/blob/main/docs/platform/api/javascript-sdk.md

Opens a project from GitHub in StackBlitz, either in a new tab or the current window. Accepts a repository path and optional display options.

```APIDOC
## openGithubProject(repoPath, openOptions)

### Description
Opens a project from GitHub in StackBlitz (in a new tab or in the current window).

### Method
SDK Method

### Signature
`openGithubProject(repoPath, openOptions)`

### Parameters
- **repoPath** (String) - Required - The repository path (with optional branch/tag/commit/folder).
- **openOptions** (OpenOptions, Object) - Optional - Display options for the StackBlitz editor.

### Request Example
```js
// Imports https://github.com/username/repository-name to StackBlitz,
// and opens the resulting StackBlitz project in the current tab
sdk.openGithubProject('username/repository-name', {
  newWindow: false,
});

// Imports the 'examples/getting-started' sub-folder of the 'main' branch of
// the https://github.com/username/repository-name repository to StackBlitz,
// and opens the resulting StackBlitz project in a new tab
sdk.openGithubProject('username/repository-name/tree/main/examples/getting-started');
```

### Response
No return value is documented.
```

--------------------------------

### StackBlitzSDK.openProject options

Source: https://github.com/stackblitz/docs/blob/main/docs/guides/integration/create-with-sdk.md

The options object passed as the second argument to the StackBlitzSDK.openProject method allows customization of the project behavior, including the file to open, window behavior, dev tools visibility and height, initial path, and origin for enterprise deployments.

```APIDOC
## StackBlitzSDK.openProject(options)

### Description
Customizes the behavior of a StackBlitz project when opened via the SDK. The options object is passed as the second argument to the `StackBlitzSDK.openProject` method.

### Method
`openProject` (SDK method)

### Parameters
#### Options Object
- **openFile** (string) - Optional - The path of the file to display in the editor on page load. Example: `'src/app/index.tsx'`.
- **newWindow** (boolean) - Optional - Set to `false` to open the project in the same browser window instead of a new one. Default is `true`.
- **hideDevTools** (boolean) - Optional - Set to `true` to hide the console in projects not powered by WebContainers. Default is `false`.
- **devToolsHeight** (number) - Optional - The height (as a percentage) of the console in the preview window for projects not powered by WebContainers. Default is `33`.
- **initialPath** (string) - Optional - The path to be opened by the preview window. Example: `'/posts'`.
- **origin** (string) - Optional - The origin URL of your StackBlitz Enterprise Edition server. Example: `'https://our-sb-instance.internal.excellent-company.com'`.

### Request Example
```js
{
  openFile: 'src/app/index.tsx',
  newWindow: false,
  hideDevTools: true,
  devToolsHeight: 50,
  initialPath: '/posts',
  origin: 'https://our-sb-instance.internal.excellent-company.com'
}
```

### Response
No response body is documented. The method returns a promise or void as per the SDK implementation.
```

--------------------------------

### Export PostgreSQL database with pg_dump

Source: https://github.com/stackblitz/docs/blob/main/docs/enterprise/data-migration.md

Run this command on a host with kubectl access to export the stackblitz_production database. It finds the postgres pod, runs pg_dump, and compresses the output to stackblitz_dump.sql.gz. Replace K8S_NAMESPACE with your namespace.

```bash
K8S_NAMESPACE=<your stackblitz namespace> \
PG_POD=$(kubectl get pods -o name -n $K8S_NAMESPACE| grep 'postgres' | grep -v 'kots') && \
kubectl exec -n $K8S_NAMESPACE -it $PG_POD -- sh -c \
'pg_dump --if-exists -xcCO \
-U $POSTGRES_USER \
-d stackblitz_production' | \
gzip > stackblitz_dump.sql.gz
```

--------------------------------

### Configure repository URL in .storybook/preview.ts|js

Source: https://github.com/stackblitz/docs/blob/main/docs/guides/integration/storybook-addon.md

Set the repository URL in the Storybook preview configuration so the addon knows which repository to open.

```tsx
export default {
  parameters: {
    repositoryUrl: 'https://github.com/[username]/[reponame]'
  },
};

```

--------------------------------

### Add the addon to .storybook/main.ts|js

Source: https://github.com/stackblitz/docs/blob/main/docs/guides/integration/storybook-addon.md

Add the StackBlitz addon to the Storybook main configuration file.

```tsx
export default {
  addons: ['@stackblitz/storybook-addon-stackblitz'],
};

```

--------------------------------

### Embed StackBlitz project in an iframe

Source: https://github.com/stackblitz/docs/blob/main/docs/guides/integration/embedding.md

Paste the embed URL into an iframe to display a StackBlitz editor on your page. The example uses the embed URL for an Angular project with the embed=1 parameter.

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