Skip to content

Quickstart

Point hiiu at a Vite or Next app, read what it found, build a base, run it on loopback, and crawl it.

This runs the pipeline by hand, one command at a time, so you can see what each step produces. hiiu init does the same sequence in one command once you trust it.

You need a React app built with Vite or Next, on a committed revision. Nothing below writes to your repository.

1. See what hiiu thinks your app is 

hiiu analyze ./path/to/app

It reports the framework, the router, the routes it walked and the API handlers it found. It reads only the filesystem: no network, no LLM, no prompts, and two runs of one input are byte-identical.

If it exits 3 with NO_SUPPORTED_APP, point it at the directory holding the app's package.json rather than at the repository root. hiiu never picks an app out of a workspace for you, because which app is a decision, not a fact.

2. Read the contract it compiled 

hiiu ir ./path/to/app

The contract IR is the app's declared API surface as one document: every endpoint hiiu knows the app can call, from the router's own claims and from any MSW handlers the repo already has. A repo with no declared API surface is zero endpoints and exit 0, not an error.

3. See what it will inject 

hiiu overlay ./path/to/app

This prints the interception overlay: the files that make every request leaving the app a recorded refusal unless it goes to loopback. It prints and never writes.

4. Build the base 

hiiu build ./path/to/app

This mirrors the committed revision into a content-addressed base under ~/.cache/hiiu/bases/, writes the overlay over it, and installs with the app's own package manager and lockfile. The first build is slow because it is a real install. The second build of an unchanged revision is a cache hit that re-runs nothing.

A dirty working tree is exit 3. Commit or stash first: a base is addressed by the revision it came from, so an uncommitted change has no address.

5. Run it 

hiiu dev ./path/to/app

This resolves the base exactly as build does, then runs the app's own dev script inside it on a loopback port. Hot reload keeps working, because hiiu wraps the app's toolchain rather than replacing it.

Leave it running.

6. Crawl it

In another terminal, pointing at the port dev printed:

hiiu verify --url http://127.0.0.1:5173 ./path/to/app

This visits every declared route and reports which rendered and what went unmatched.

What you have now

A base in ~/.cache/hiiu/bases/, and a measurement of how far the app is from running without its backend. Nothing was written to your repository, and no CI was touched.

From here: