0.2.0 release notes

Version availability

These notes describe the source changes in the v0.2.0 tag compared with v0.1.0. Check the npm package for installable versions; a Git tag and npm publication are separate steps.

More reliable server detection

• Workspace package managers: child apps can inherit a package manager from a parent packageManager field or lockfile. Discovery uses the nearest match and stops at the Git or workspace root. Build and start use the same rules.
• Port estimates: explicit and script ports remain checked for conflicts. An occupied framework or generic default no longer blocks a command from starting; flash-tunnel waits for its actual local URL. It excludes the already occupied estimated port rather than automatically reusing that service.
• Explicit-command ports: --port, -p, and PORT= can be read from an explicit startup command as well as project scripts. An explicit flash-tunnel port setting takes priority.
• Consistent startup plans: the CLI's selected command, working directory, reason, and confidence are passed to the session without a second detection pass.
• Stable errors: NO_RUNNABLE_SCRIPT identifies missing runnable servers. Non-interactive workspace selection reports WORKSPACE_REQUIRED with candidate paths.

See local servers and troubleshooting.

Vite previews without manual host changes

flash-tunnel sets Vite's additional allowed-host environment variable for the servers it starts: the exact named-mode hostname, or .trycloudflare.com in quick mode. Existing values are preserved. Servers started separately still need their own allowed-host configuration.

Detected dev-server URLs use only the origin, so an additional printed path such as /presenter/ or /__mcp does not become the tunnel's upstream path.

State outside the project

Runtime state and logs live under ~/.flash-tunnel/, including project data in projects/<project-key>/ and the session index in sessions/. Inactive project data is pruned after seven days by default; FLASH_TUNNEL_RETENTION_DAYS=0 disables pruning.

Cleanup uses shared process-tree handling and a unified teardown path. See cleanup and recovery for normal shutdown, watchdog recovery, and manual retries.

Upgrade considerations

• A monorepo app that previously fell back to npm may now use the root's pnpm, Yarn, or Bun selection. Check closer declarations and lockfiles if the result is unexpected.
• If an estimated port is occupied and the server prints no URL, supply its actual port explicitly. Set the port in the server's own configuration too; --port does not rewrite the command.
• Reuse remains an explicit choice through --reuse, a port-conflict prompt, or --url <url> --attach.
• @flash-tunnel/core callers can supply an optional serverPlan to startPreviewSession. Plans expose optional packageManagerSource and portSource metadata. Manually constructed command plans without portSource use strict port checks.

Requirements remain Node.js 22.14+ and an installed cloudflared executable. The project remains in early development (0.x).