[3m1n3nc3]

Summary

Adds Fastify as a third runtime next to Express and H3. This was the top item on the roadmap.

Commits

1. refactor: shared ServerDriver. The Express and H3 drivers each had their own copy of the bind address setup, the ngrok tunnel, the startup lines and the server:start hook. That code now lives in a ServerDriver base in @arkstack/common, and each driver only implements its listen call. The ngrok dependency moves to common. The driver tests now stub ServerDriver.forward instead of mocking @ngrok/ngrok.
2. feat: @arkstack/driver-fastify.
   • The driver, Router, error handler, and the auth, resora, formdata, requestLogger and limiter middlewares.
   • Middleware positions map to Fastify hooks: global runs on onRequest, before on preHandler, and after on onResponse.
   • A callback middleware's done runs inside the middleware's own async context, so localeMiddleware() still sets the locale for the handler.
   • Fastify plugins come in through a plugins option. Formbody and multipart are on by default, and static files are served with @fastify/static.
   • The error handler is set in createApp(). Fastify fixes a route's error handler when the route is built, and route setup is async, so setting it later missed some routes.
3. feat: templates/fastify.
   • The same app as the Express template.
   • CORS is set up in src/config/plugins.ts.
   • boot() sets the app up only once, because parasito calls startup() for every request.
   • CI and publish run pnpm prepare for this template, and the release script bumps its version.
4. feat(create-arkstack). Adds the Fastify option. The Inertia prompt is skipped for Fastify, and an explicit --stack is rejected, because there's no Fastify Inertia adapter yet.
5. docs. A new runtime guide at docs/guide/fastify-runtime.md, plus updates to the README (Fastify listed as Beta), the roadmap, getting started, AGENTS.md and SKILL.md.

Before this is ready to merge

This PR depends on two upstream fixes:

• feat: support Fastify replies in ServerResponse and resources resora#7. Without it, clearRouterFastifyPlugin returns the body after the reply was sent, and Fastify logs FST_ERR_REP_ALREADY_SENT on every resource response. driver-fastify/tests/router.test.ts covers this, and it's the only test that fails on this branch right now.
• fix: share one POST route per path for Fastify method overrides clear-router#2. Without it, the Fastify adapter registers a separate POST route for each PUT, PATCH and DELETE override, so apiResource crashes on startup with Method 'POST' already declared.

Once both are released, the @resora/plugin-clear-router, resora and clear-router catalog versions need bumping here.

Tests

• I ran the local suite against a local Postgres. With both upstream fixes patched into node_modules, all 674 tests pass. Without them, everything passes except the one resora test above.
• pnpm lint and pnpm build:templates pass.
• I built and started the Fastify template. These all worked: /api, /api/users against the database, a DELETE through a _method POST, the welcome view, static files, a 404 as an Arkstack JSON error, CORS preflight, and ark route:list.

[codecov]

Codecov Report

❌ Patch coverage is 89.23077% with 28 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
packages/driver-fastify/src/FastifyDriver.ts	87.09%	8 Missing ⚠️
packages/driver-fastify/src/error-handler.ts	83.33%	7 Missing ⚠️
packages/common/src/ServerDriver.ts	89.36%	5 Missing ⚠️
...ackages/driver-fastify/src/middlewares/formdata.ts	80.00%	4 Missing ⚠️
packages/driver-fastify/src/Router.ts	84.21%	3 Missing ⚠️
packages/driver-express/src/ExpressDriver.ts	80.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!