Discovery and Serving
How a Dev Preview session comes up: script discovery and command ranking, Turbopack handling for Next.js, port allocation, the stable proxy origin in front of your server, and what happens to a session when you stop it, close the panel, remove its worktree or relaunch.
Automatic discovery
Daintree scans the project for runnable commands. Detection covers nine sources:
package.jsonscripts: the runner follows your lock file (bun.lockorbun.lockbuses bun,pnpm-lock.yamluses pnpm,yarn.lockuses yarn, otherwise npm)- Makefile targets (excluding dot-prefixed and special PHONY rows; normal targets declared phony are still useful commands)
- Justfile recipes (skips underscore-prefixed entries)
- Taskfile.yml tasks (only those with a
descfield) - Procfile: every
NAME: commandline, with the command body used verbatim - mise.toml:
[tasks]entries with arunfield, skippinghide = trueand_-prefixed tasks; surfaced asmise run [name] - Django
manage.py: common commands likerunserver,migrate,test, andshell composer.jsonscripts (non-lifecycle).devcontainer/devcontainer.json: thepostStartCommandin string, array, or object form, withnohup, a trailing&, andbash -cwrappers stripped
Detection results are cached for up to 60 seconds, but only while none of the files above has changed: adding a package.json or editing a script invalidates the cache on the next look. Detection also runs again each time a Dev Preview panel opens, so a project scaffolded after you added it to Daintree still offers its dev script. Every discovered command also feeds the QuickRun autocomplete.
How a candidate is ranked
Ranking is framework-aware before it is name-based. If your dependencies name a framework Daintree recognizes (Next.js, Remix, React Router, Nuxt, SvelteKit, Astro, Create React App, or plain Vite) and that framework's canonical script exists and actually invokes it, that script wins. This is why a Create React App project offers start rather than being pushed down the list by a dev script that does something else.
After the framework default come scripts named dev, then start, then serve. If none of those matched, a .devcontainer postStartCommand is offered next, then every other detected runner.
next dev, either directly or through a package script whose body is a plain next dev, Daintree checks the installed Next.js version before spawning the server. The version is read from node_modules/next/package.json, falling back to your package.json dependencies. On Next.js 15 it appends
--turbopack. On Next.js 16 and newer, it treats Turbopack as the default and leaves the command as it is. The Next.js CLI reference documents this default and the --webpack override. On Next.js 14 or older, or when the version can't be determined, it strips any --turbopack flag instead. This is a compatibility preference for embedded previews; it does not migrate custom webpack configuration. The flag goes after
-- for npm (npm run dev -- --turbopack) and directly after the script name for pnpm, yarn and bun, which forward extra arguments themselves. Commands, or package script bodies, containing shell control characters (&&, ;, |, redirection, substitution) are left alone, because the flag would attach to the wrong program. A command or script that already passes --webpack wins: Daintree leaves it untouched and records Bundler preference not applied in the Diagnostics timeline. Turn it off per project with Use Turbopack for Next.js in the Dev server section of project settings (on by default). Disable it if your project relies on a custom
webpack() config, a .babelrc, or loaders that aren't Turbopack-compatible (SVGR is a common one). With it off, Daintree strips any --turbopack flag it would have added, and on Next.js 16 it adds --webpack so the preference still means webpack. The exception is a package script that asks for Turbopack itself: Daintree doesn't rewrite your scripts, so it leaves that one alone and records the conflict in Diagnostics.Port pinning
Daintree allocates a port for each session, and for the frameworks that ignore process.env.PORT it injects the port into the command rather than hoping to detect it afterwards. Vite and SvelteKit get --port plus --strictPort, so the server fails fast on a collision instead of quietly drifting to the next free port and leaving the readiness probe watching the wrong URL. Astro and Nuxt get --port only, since they don't forward --strictPort to Vite. A command that already specifies a port is left alone, as is any command with shell control characters in it.
For frameworks Daintree can't pin, it still knows the conventional default port (3000 for Next.js, Remix, Nuxt and Rails, 5173 for Vite and SvelteKit, 4321 for Astro, 8000 for Django and Laravel, 4000 for Phoenix) and uses it to aim the readiness probe.
How the preview is served
The webview never loads http://localhost:<devPort> directly. Daintree runs a small reverse proxy on a fixed port (43000, or an OS-assigned fallback if that one is taken) and gives every panel a stable origin of the form http://dp-<token>.localhost:<proxyPort>. Each request is forwarded to whatever port that panel's dev server is on right now, resolved live.
You rarely see that origin. The address bar translates it back to the dev server's own address and route, so it reads localhost:5173/dashboard while the page is really loaded from the proxy, and Copy URL copies that readable address. Typing a dev-server address, or following a redirect that names one, lands on the same route through the proxy instead of dropping back to its root.
That indirection buys three things:
- Cookies and
localStoragesurvive a restart. Restart the dev server and it may come back on a different port, but the origin the page was loaded from does not change, so origin-scoped storage remains available. A changed proxy port after an app relaunch creates a different origin, so this is not a guarantee across every restart of Daintree itself. - Host checks pass. The proxy rewrites the
Hostheader to the upstream, so Vite and Next.js host validation sees what it expects, and it strips theDomain=attribute from upstreamSet-Cookieheaders so cookies bind host-only to the stable origin instead of being rejected. - IPv6-only and HTTPS dev servers work. The upstream is dialed as
localhost, not127.0.0.1, so a Vite server that bound IPv6-only still resolves; and a dev server running over TLS (Vite'sserver.https, Next.js--experimental-https, mkcert) is dialed over HTTPS rather than answered with a 502.
A stalled upstream is dropped after 30 seconds and surfaced as a classified 502, rather than leaving the webview spinning forever.
In a window on a remote host, the dev server runs on the host. Dev Preview reaches it through the host and forwards its port to this machine on demand, over the existing ssh connection. The forward is listed in the Ports view as Dev preview and is dropped when the dev server goes away.
Opening the page in your real browser
Open in external browser does more than hand your default browser a URL. Daintree mints a short-lived, single-use, panel-bound HMAC token and opens a bootstrap URL carrying it. The external browser redeems the token once, picks up a session marker on the same stable origin, and redirects to the page you were looking at. This marker belongs to Daintree's proxy; it does not transfer your application's login cookies, localStorage, or IndexedDB from Electron into the external browser. You may need to sign in there separately. Tokens live for 60 seconds and never outlive the app process; the key is generated per run and is never persisted.
Session lifecycle
Each panel's dev-server session is keyed by project and panel, and survives panel remounts, rearrangement and a move to the dock without restarting the server. In the dock the live preview moves into the dock popover, and the dock row itself is only a label. If the server is still starting a moment after launch and no URL has been seen, Daintree re-reads up to its last 300 lines of output, so an address printed before it was watching is not missed.
Stops that stick
A stop you ask for stays in effect. Whether it came from the drawer's Stop dev server button, the links launcher's Dev servers list, a worktree card's menu or the Running processes view, Daintree records the intent and refuses to start that panel's server again on its own: not when the panel remounts, not when the project hibernates and wakes, and not after a relaunch. The panel shows Start the dev server until you press Start dev server or pick a restart option. Closing the panel or deleting its worktree forgets the intent along with the session.
A stop is confirmed against the process actually exiting, not just against the kill being sent. A server that ignores the stop signal is terminated after 5 seconds, and the panel says so with a Dev server was force-quit banner. One that is still running after that stays tracked rather than forgotten: the panel reports Dev server didn't stop within 8s. Stop it again, or close the project to retry., and Daintree will not start a second server beside it while it is still exiting.
Removing a worktree outside Daintree, for example with git worktree remove in a terminal, stops that worktree's dev server once Daintree confirms the folder is gone.
Across a relaunch
Running sessions are recorded in a manifest when they enter a running state and at shutdown, so a crash can also leave a restart offer. The manifest holds spawn metadata only (working directory, command, environment, Turbopack setting) and no process handle: nothing is reattached, and the next start allocates a fresh port rather than reusing one that may now be in TIME_WAIT or taken by something else. On the next launch, opening the project brings the server back: the panel re-issues the saved command when it mounts. Until then the session stays listed in the links launcher's Dev servers section as Stopped with a Start button (open it with Open links from the command palette if the toolbar button is hidden), and Diagnostics marks its status (restored). If the panel shows Restart the dev server ("It was running when Daintree closed, and wasn't reattached."), press Restart dev server. A server you stopped yourself is not in the manifest, so it stays stopped.
Lazy loading and memory
The embedded browser isn't created until the panel is first visible; until then the panel reads "Preview will load when this panel is first viewed". A background panel may also have its webview released under memory pressure, in which case the panel shows "Preview paused to save memory" and recreates the webview the next time you open it.
Scroll position is saved when a panel unmounts and restored when the same URL loads again. Restarting the dev server clears the saved position, since the page content has changed.