Troubleshooting & FAQ

Most first-run problems come from one of a few places: the decorator toolchain, ESM, the .stone codegen, or workspace type resolution. Here is how to recognise and fix each, plus answers to the questions that come up most.

#Decorators do nothing / metadata is missing

Stone.js uses TC39 stage-3 decorators (the 2023-11 standard) with Symbol.metadata, not the legacy TypeScript ones. If a decorator seems ignored, your toolchain is almost certainly emitting the old form. Do not enable experimentalDecorators or emitDecoratorMetadata, and never install reflect-metadata. The Stone.js CLI already configures Babel correctly; if you run your own build, use the stage-3 plugin:

{
  "plugins": [["@babel/plugin-proposal-decorators", { "version": "2023-11" }]]
}

#Stale build after editing code (the .stone folder)

The CLI generates a .stone/ directory (module manifest, route table, entry) at build time. If a newly added handler, page or command is not picked up, the codegen cache is stale. Clear it and rebuild:

stone cache clear      # drop the .stone codegen cache
npm run dev            # or: npm run build

Commit nothing from .stone/ or dist/: both are generated.

#any types or unresolved @stone-js/* imports in a monorepo

Type-aware tools (your editor, tsc, type-aware lint) read a dependency's types from its built dist/*.d.ts. In a fresh workspace clone where nothing is built yet, imports from sibling @stone-js/* packages can resolve to any. Build once so the declaration files exist:

pnpm build             # build every package (topological)
# or a single graph:  pnpm --filter @stone-js/core... build

#"No response was returned"

A handler must return a value; the kernel resolves that value into a response per event. An InitializationError: No response was returned means a handler path returned undefined. Return the payload (or an explicit response), and remember that the status code belongs to the platform layer, not your domain: a bare returned value becomes a 200 over HTTP, an exit code on the CLI.

#A route 404s unexpectedly

A missed match is a not-found the error handler maps to 404, never a crash. Check precedence (static beats dynamic), host/domain constraints, and the HTTP method. Add a fallback route for a friendly page. See Matching & precedence.

#FAQ

#Do I have to use decorators?

No. Every declarative decorator has an imperative define* equivalent, at parity. Pick either; mix if you like.

#Which adapter do I choose?

You do not choose one, you stack the ones you target (@NodeHttp, @Fetch,@AwsLambdaHttp, @Mcp…). The runtime that receives the request collapses the choice; the domain is written once.

#TypeScript or JavaScript?

Both. The JavaScript variants keep stage-3 decorators and strip types; there is no second source to maintain.

#Is it production-ready?

The framework is in beta ahead of a 1.0. See the versioning policy for what stability the current line promises before you adopt it for a critical workload.