Workspace Templates, Pools, and Replace Behavior
How the template gallery works, what details like publish target and entry file mean, and why applying a template can replace files or restart the workspace on a different pool.
Workspace Templates, Pools, and Replace Behavior
Where you see this in the app
This page explains the Browse templates flow inside the post workspace panel.
Authors use it when they want to start from a prepared project instead of assembling the workspace manually. The template gallery appears as a chooser dialog with searchable cards and a Use template action.
What Browse templates does
Browse templates is a project replacement tool.
From an end-user standpoint, the important rule is simple: applying a template is meant to replace the current workspace project files with the selected starter project.
That is why the app warns with language such as Replace the current workspace files with this template?
If no workspace session is active yet, the template can also be applied on first launch so the workspace boots directly into that starter project.
How to read template cards
Template cards are there to help users choose the right starting point.
Common fields:
| Field | What it means |
|---|---|
| Name | The starter project identity |
| Version | Which packaged revision of the template you are using |
| Estimated size | Rough project size to expect |
| Entry file | The main file the template expects as its starting point |
| Publish | The publish directory, entry path, and routing mode when the template includes a publishable site |
| Build | The build command, when the template expects one |
| Stack tags | The main technologies or environment hints |
These fields are selection hints. They help users choose a good starter project before committing to the replacement.
Replace behavior and first boot
There are two common cases:
| Situation | What happens |
|---|---|
| Active edit-mode workspace already connected | The template is applied into the running workspace and the preview restarts |
| No active workspace session yet | The workspace launches and seeds itself from that template on first boot |
This distinction matters because users may see either Template applied or a more first-launch-oriented message such as Template selected. The workspace will initialize from it on first boot.
Pool mismatch and restart behavior
Some templates require a different workspace pool than the one currently running.
When that happens, the app does not silently continue on the wrong runtime. Instead it can restart the workspace and tell the user that the template requires a different runtime pool.
Users should interpret that restart as normal template compatibility handling, not as a failed apply.
The main mental model:
- templates can carry runtime expectations,
- those expectations can affect which workspace pool is needed,
- applying a template can therefore trigger a restart to relaunch on the correct pool.
Related docs
Related docs
See it in action
Previous
Workspace Defaults, Env Vars, and Runtime Commands
How the Defaults tab controls live preview startup, static preview and published-site paths, JSON env/secrets, and who can open or edit a workspace.
Next
Workspace Template Archive ZIP and Export Fidelity
How template ZIP archives are produced, what they preserve, and why advanced users should not assume the archive contains every ignored or controller-only file from a running workspace.