What does run do?
A site is not finished until it has been seen running. Source tells you what someone intended; the browser tells you what a person gets. This skill is the shortest path between a folder and a rendered page.
Run it
node <skill folder>/scripts/serve.mjs <dir> [--port 4173] [--open] [--shot out.png] [--stop] [--detect]
--detectprints what it found and starts nothing. Do this first when the folder is unfamiliar.--portstarts looking there and takes the next free port, so two projects can run at once.--openopens the default browser.--shot out.pngrenders the page at 1440 wide, full height, through Playwright.--stopkills the process tree from.run/state.json.
It writes .run/state.json (pid, port, url, command) and .run/server.log beside the project. Those two files are the whole handover between the start and the stop.
What it detects
| Finds | Runs |
|---|---|
package.json with dev, start, serve or preview | npm run <that script> on a free port, with PORT set |
index.html in the root | python -m http.server on that folder |
public/index.html, dist/index.html, build/index.html | a static server rooted at the built output |
| A config file but no scripts | reports it and stops: the project needs its own command |
go.mod, Cargo.toml, pubspec.yaml | reports it and stops: use the project's own run command |
Framework specifics, port defaults and the failure modes worth knowing: references/stacks.md.
Reading the result
The script proves three things and nothing more: a process started, a port answered, a page rendered. What it cannot tell you:
- whether the layout is right at 375, 768 and 1440 (use
sitecraft/scripts/verify.mjsfor that) - whether the console is clean (it is not captured here;
verify.mjscaptures it) - whether the page it screenshotted is the page the user meant (check the URL against the route you asked for)
So the loop is: serve.mjs --shot, look at the picture with your own eyes, fix, shoot again. Three renders is the cap for one pass; past that, the problem is the plan, not the CSS.
Rules
- Never leave a server running. Stop it when the check is done, or say plainly that it is still up and on which port. A stray dev server on the user's machine is a mess they have to clean.
- Do not start what you cannot stop. If the project needs Docker, a database or a paid API key, say so before spawning anything.
- Report the real URL.
localhost:4173, not "the app". If the port moved because 4173 was taken, say the new one. - Read the log before guessing. A failed start is almost always a missing dependency, a missing env var or a port already bound.
.run/server.loghas the answer, and quoting the actual error beats a theory. - No installs without saying so. If
node_modulesis missing,npm installis usually right, and it is also a mutation of their project. Do it, then say it ran, or ask once when the install is large. - Static over framework. When a built output exists and is current, serving
dist/is faster and truer than the dev server.
When it will not start
- Read
.run/server.logand quote the first real error, not the last line. - Missing dependencies:
npm installin the project, then retry. - Missing env: look for
.env.example, name what is required, and stop if a value is secret and absent. - Port already bound: the script already steps to the next free port; a hardcoded port in the framework config is the usual cause when it still fails.
- Build step required: run
npm run buildfirst, then servedist/. - Native or containerised: hand back the command the project documents. Not every stack is a script.
Checklist
- Detected the stack rather than assumed one
- Started it and saw a real HTTP answer, not just a spawned process
- Reported the exact URL and port
- Looked at a screenshot, not only at the log
- Checked the route matches the page that was meant
- Stopped it, or said it is still running and where
- Quoted the real error when it failed