Project configuration
Projects based on WebContainers can be configured:
- with project files (
package.json
or.stackblitzrc
); - with URL parameters.
With project files
Projects can be configured using the stackblitz
field in the package.json
file at the root of the project. For example:
{
"name": "lib-example",
"version": "1.0.0",
"license": "MIT",
...
"stackblitz": {
"startCommand": "npm start"
}
}
Alternatively, use a .stackblitzrc
file at the root of the project. The expected format is valid JSON (without comments). This may look like:
{
"installDependencies": false,
"startCommand": "my-custom-command",
"env": {
"NODE_ENV": "development"
}
}
installDependencies
Type | boolean |
Default | true |
StackBlitz automatically installs npm dependencies when opening a project.
To disable this behavior, set installDependencies
to false
.
startCommand
Type | string | boolean |
Default | Inferred from the contents of package.json |
A terminal command to be executed when opening the project, after installing npm dependencies.
If not specified, StackBlitz will look at the project’s root package.json
(if any), and select a command to run using the following criteria:
- We may select a framework-specific command in some special cases;
- Or, if
package.json
defines a"dev"
script: executenpm run dev
; - Or, if
package.json
defines a"start"
script: executenpm start
.
To disable this behavior, set startCommand
to false
(which means: "do nothing") or provide a custom command.
compileTrigger
Type | "auto" | "keystroke" | "save" |
Default | "auto" |
The compileTrigger
option controls how file changes in the editor are written to the WebContainers in-memory filesystem. Note that writing to this in-memory filesystem does not mean that changes are persisted on stackblitz.com
(this requires a separate “Save” action from users).
The available settings are:
"auto"
(default): changes are synced automatically when modified, after a short delay;"keystroke"
: changes are synced immediately, on every edit;"save"
: changes are synced when users manually save the project (using the “Save” button or a keyboard shortcut).
This option can be useful if your project runs a development server (such as Vite or webpack-dev-server), which compiles user code whenever source files change.
The default "auto"
setting can show the result of changes as users type, giving a nice reactive feel to project demos. But this also means that the development server or compiler used in the project may receive invalid code as users type. Since not all dev servers and compilers are resilient to invalid input, you may want to set compileTrigger
to "save"
instead to limit errors.
env
Type | Record<string, string> |
Default | {} |
A map of default environment variables that will be set in each top-level shell process.
With URL parameters
terminal
Use the terminal
parameter in the project URL’s query string to select one or several scripts from package.json
to run on project load.
This can be useful when a project doesn’t define a custom startCommand
, or if you want to share a link that runs a different script that the one specified in startCommand
.
For example, the following URL will run the "test"
script defined in package.json
, on project load:
https://stackblitz.com/edit/project-id?terminal=test
important
The terminal
parameter only accepts existing keys from the package.json
’s scripts
field. Projects which need more control should use configuration in the project files directly.
You can also run several scripts sequentially using comma-separated values. For instance, if a project defines a "build"
script and a "serve"
script, and both are needed to render a web page, you could use:
https://stackblitz.com/edit/project-id?terminal=build,serve