Set up h34s with a coding assistant
Copy the prompt from the code block below into your coding assistant. The prompt asks the assistant to perform the steps of the adoption guide on any of its three paths. Nobody has run this prompt end to end with an assistant yet, so review every change that the assistant reports.
Before you start
- Create a classic GitHub personal access token with
read:packages. Authenticate package reads says which account and access it needs. - Set
GITHUB_PACKAGES_USERto the GitHub username that owns the token, andGITHUB_PACKAGES_TOKENto the token, in your shell or secret manager. sbt reads both variables. npm reads the token through.npmrc, as in Install the tooling. - Start the assistant from a shell where both variables are set. Never paste the token into the chat: the assistant needs only the variable names.
The prompt
You are adding h34s 0.2.0-alpha.1 (Scala.js server handlers for Nuxt) to this project. Follow the
guides `docs/content/1.guide/02.adoption.md`, `docs/content/2.reference/2.releases.md` and
`docs/content/1.guide/13.npm-tooling.md` in the `yuri4n/h34s` GitHub repository, and these
rules. If you cannot read a guide, ask me to paste the section.
1. Ask me three things first, and wait for my answers: the effect API (Kyo or ZIO; default Kyo),
the Scala directory (default `scala-server`) and the Scala package. The default package is
the project directory's name in lower case, letters and digits only, if the result starts
with a letter and is not a Scala keyword. Otherwise, there is no default: ask me for a name.
2. Never write, print or commit a token, including one you find in a file. Use only
environment-variable references: `${GITHUB_PACKAGES_TOKEN}` in `.npmrc`, and
`sys.env.get("GITHUB_PACKAGES_USER")` and `sys.env.get("GITHUB_PACKAGES_TOKEN")` in sbt.
Check whether a variable is set without printing it, for example `test -n "$GITHUB_PACKAGES_USER"`.
If one is not set, tell me its name and continue; skip the steps that download packages.
3. Detect the path in the directory I name (default: this one). The first match wins:
- `h34s.config.mjs` exists: stop. The project is already set up.
- The directory is missing, empty, or holds only `.git`: a new project. Create a minimal
Nuxt 4 app with `nuxt` pinned to 4.3.1, then add the sbt build in it.
- `nuxt.config.*` exists: an existing Nuxt app. Add the sbt build at the Nuxt root. If
`build.sbt` exists there too, put the h34s settings in a new `h34s.sbt`.
- `build.sbt` exists and no `nuxt.config.*`: an existing sbt build. Create a minimal Nuxt 4 app
with `nuxt` pinned to 4.3.1 at the sbt root, and put the h34s settings in a new `h34s.sbt`
next to `build.sbt`. In your report, remind me that the modules my handlers depend on must
cross-build for Scala.js and use Scala 3.9.0.
- Anything else: stop and ask me.
4. Change a file that existed before you started only by adding lines or entries; never
overwrite it. Never edit an existing `build.sbt`. If a file you must create, such as
`server/api/hello.get.ts`, already exists, ask me.
5. Use these versions: JDK 25 to run sbt, sbt 1.11.7, Scala 3.9.0, `sbt-scalajs` 1.22.0, Node 24,
`"dev.yuri4n" %%% "kyo-h3-ext" % "0.2.0-alpha.1"` (for ZIO, `zio-h3-ext`), pnpm 10.34.4,
`@yuri4n/h34s-nuxt@0.2.0-alpha.1` and `h3@1.15.4`. If `java -version` differs, tell me. If an
existing app's Nuxt version is not 4.3.1 or 4.4.2, stop and ask me before you change anything.
6. Take the sbt files and the server project from "Configure the Scala.js module" in the adoption
guide, with my Scala directory. Add the resolver and credentials block from "Authenticate
package reads" on the Releases page. If `project/` sets another `sbt.version` or `sbt-scalajs`
version, or the build already has a project named `server`, ask me.
7. Add the two `.npmrc` lines from "Install the tooling" in the npm tooling guide. Skip a line
that `.npmrc` already holds. If `.npmrc` configures the `@yuri4n` scope or
`npm.pkg.github.com` in another way, ask me.
8. Do not run `nuxi module add`. Run `pnpm add -D @yuri4n/h34s-nuxt@0.2.0-alpha.1` and
`pnpm add h3@1.15.4`.
9. Write `h34s.config.mjs` from "Write, mount and run a handler" before you add
`'@yuri4n/h34s-nuxt'` to `modules` in the Nuxt config. The module stops Nuxt when that file
is missing. Edit the Nuxt config yourself.
10. Use the scripts from "Add the Nuxt module and scripts" in the npm tooling guide. Add the
missing ones, and replace the ones you created, such as the `dev` and `build` scripts of a
new Nuxt app. If `dev` or `build` existed before you started, do not replace it; show me the
change instead, because `build` must run `pnpm run scala:full` before `nuxt build`.
11. Write the handler from "Write, mount and run a handler" in my package, as `Hello.scala` in
`src/main/scala/` of my Scala directory, and its route file `server/api/hello.get.ts`.
For ZIO, import `dev.yuri4n.exts.zioh3.*` instead of `dev.yuri4n.exts.kyoh3.*`, add
`import zio.ZIO`, and define the handler as
`ZHandler.define(_ => ZIO.succeed(Greeting("Hello from Scala")))`.
12. Keep `server/.scala` for generated files only: a production build deletes it. If it already
holds files, ask me. Add the missing `.gitignore` entries: `server/.scala/`, `target/`,
`project/target/`, `project/project/`, `.bsp/` and `.metals/`, and for a new Nuxt app also
`.nuxt/`, `.output/` and `node_modules/`.
13. Verify: run `pnpm install`, start `pnpm dev:scala` in the background, wait until Nuxt
listens, request `http://127.0.0.1:3000/api/hello` (or the port Nuxt prints), then stop the
server. Expect `{"data":{"message":"Hello from Scala"}}`.
14. Do not commit. Report the result, every file you created or changed, and every step you
skipped or that I must do myself.
If something fails
Start with the recovery notes at the end of Write, mount and run a handler: they cover a 404, an h3 that Nitro cannot resolve, and a missing linked module. If Nuxt stops with Missing h34s config, create h34s.config.mjs next to package.json, as in the adoption guide. For HTTP 401 or 403 from a registry, check the token and its access in Authenticate package reads. For a 500 or a stack trace, see debugging. What is verified says which parts of this setup have been tested.