Sites Lifecycle

The Sites initializer copies the shared starter and selects managed-linux only when SITES_MANAGED_LINUX_CONTAINER=1; otherwise it selects portable. It saves the selection only in ignored .sites-runtime/execution-profile.json. Both profiles copy/configure first, then use the plugin's separate install-dependencies.mjs step to measure installation independently. Edit source under app/ and follow the Sites skill for installation, preview, builds, and publishing.

Run node <plugin-root>/scripts/configure-execution-profile.mjs only when the profile is unknown for the current checkout and environment. Profile changes do not alter tracked source or require reinstalling otherwise-valid dependencies; restart an existing preview to use the new selection. Do not commit or upload .sites-runtime/.

This starter does not use wrangler.jsonc.

install:ci runs npm ci once against the shared lockfile, disables parent-workspace discovery, and includes required dev/optional dependencies despite production/omit settings. Sharp defaults to prebuilt binaries unless explicitly configured otherwise. Do not overlap installers.

• Portable: Preserve host HOME, npm cache, registry, proxy, temporary paths, retry/concurrency settings, and lifecycle-script policy. Use --prefer-offline --no-audit --no-fund.
• Managed Linux: Use the existing project-local HOME/cache/tmp setup and Linux install lock, tarball preflight, and timeout. Restore the image-seeded npm cache only when its lockfile hash matches; retain network fallback. Builds keep their existing timeout. These helpers are not invoked by the portable profile.

scripts/sites-env.mjs preserves the caller's HOME, npm cache, proxy, XDG, and temporary-directory configuration while defaulting Wrangler and Miniflare state to the checkout. If npm reports an unwritable cache, select a writable path with npm_config_cache for that install. The dev and start scripts also keep Wrangler logs inside the checkout. Generated .sites-runtime/ and .wrangler/ directories are disposable and ignored by Git.

On portable, npm run dev uses vinext dev with HMR, starting at port 5173. Vinext records the running server in ignored .vinext/ state, rejects an ordinary duplicate launch, and recovers stale state after a stopped process; exactly simultaneous starts can race. Pass --port <port> or --hostname <host> after npm run dev -- when needed; keep portable previews on loopback.

For browser QA on managed Linux, use sites-preview start. The project's dev script runs Vite and accepts the supervisor's --host 0.0.0.0 --port 4173 --strictPort arguments. The internal browser uses http://terminal.local:4173/; it is not a user-facing URL. The supervisor owns the preview lifecycle. The ignored local profile survives the supervisor's cleared process environment.

The portable profile simulates ChatGPT sign-in only for loopback development requests. Visit /signin-with-chatgpt?return_to=/ to sign in as local_seedy (seedy@sites.test, display name Seedy) and /signout-with-chatgpt?return_to=/ to sign out. The development cookie preserves that identity across server restarts. Mock auth is disabled in the managed-linux profile and is not included in production builds; hosted authentication remains dispatch-owned.

The Worker uses vinext/server/fetch-handler, including Vinext's config-aware image handling. After building, npm start runs that Worker locally through Wrangler on 127.0.0.1, sharing .wrangler/state with dev preview and local D1 migrations; it does not deploy the site or simulate sign-in. Use the URL printed by the server. Pass npm start -- --port <port> to select a different built-preview port.

Local previews use Miniflare's placeholder Request.cf metadata without a network lookup. Set CLOUDFLARE_CF_FETCH_ENABLED=true to opt into fetching preview metadata; this setting does not change hosted request metadata.

Local tool usage metrics are disabled by default. Set WRANGLER_SEND_METRICS=true to opt in.