Automatically handle Vite hot file during static site generation

[JoshSalway]

Summary

Fixes #185

When public/hot exists (created by npm run dev), Laravel's Vite helper switches to HMR mode and generates asset URLs pointing to http://localhost:5173/... instead of production build assets. The SSG would silently write these localhost URLs into every generated HTML file — all Vite-managed CSS and JS would be completely broken in any deployed static site, with no indication of what went wrong.

Reproduction

Confirmed locally on a real Statamic site:

Without public/hot — correct production URLs:

<link rel="stylesheet" href="/build/assets/site-DgCDvkz7.css">

With public/hot — broken localhost URLs, SSG reports success with no warning:

<link rel="stylesheet" href="http://localhost:5173/resources/css/site.css">

Fix

Before generating content files, the generator now automatically moves public/hot aside to public/hot.ssg-backup, runs generation (so Vite resolves assets from the production manifest), then restores the hot file — even if generation fails. The developer's local environment is left exactly as it was.

This also includes a second improvement: if a path in the copy config doesn't exist, a warning is now shown rather than silently skipping it.

Test plan

• it_temporarily_moves_vite_hot_file_aside_during_generation — hot file moved aside, correct URLs generated, hot file restored
• it_restores_vite_hot_file_even_if_generation_fails — hot file always restored even on failure
• it_warns_when_copy_source_does_not_exist — warning for missing copy sources
• it_copies_files_and_directories_to_destination — happy path still works
• Full test suite passes (32/32)

🤖 Generated with Claude Code

[JoshSalway]

Hi @duncanmcclean — wanted to offer some options here depending on how much change you're comfortable with. I've experimented with all four approaches as sequential commits in this branch so you can review each one directly in the commit history.

---

Option 1 — Documentation only (least invasive)

Commit: Document that public/hot must not be present during generation

No code change. Adds a note to the README explaining that public/hot must not be present when running ssg:generate, and that npm run build should always be used (not npm run dev). Low risk, zero surface area, but relies entirely on users reading docs.

---

Option 2 — Warn only

Commit: Warn when Vite hot file is present during generation

Prints a clear warning before generation if public/hot is detected, but continues anyway. The output may still have broken URLs, but at least the user knows why. Minimal code change, no side effects.

---

Option 3 — Automatically handle it (recommended)

Commit: Temporarily move Vite hot file aside during generation

Moves public/hot aside to public/hot.ssg-backup before generating, then restores it afterwards — even if generation fails (finally block). Generation always produces correct production URLs regardless of dev environment state. Most seamless for the user — just works.

---

Option 4 — Fail hard

Branch: option/4-fail-hard

Aborts generation entirely if public/hot is present, with a clear error message. Forces the user to clean up before proceeding. Zero filesystem side effects, unambiguous signal, but the most opinionated approach.

---

The first commit in the branch (Warn when a copy source path does not exist) is a standalone improvement included in all options — it warns rather than silently skipping when a configured copy source path doesn't exist.

Happy to adjust or split however works best for you.

🤖 Generated with Claude Code