[Agents] Add note about ES2021 tsconfig target for @callable() decorator

[thomasgauvin]

No description provided.

[github-actions]

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern	Owners
/src/content/docs/agents/	@irvinebroque, @rita3ko, @elithrar, @thomasgauvin, @threepointone, @whoiskatrin, @cloudflare/pcx-technical-writing, @cloudflare/ai-agents, @cloudflare/dev-plat-leads

[github-actions]

Preview URL: https://040820fe.preview.developers.cloudflare.com
Preview Branch URL: https://agents-callable-es2021-tsconfig-note.preview.developers.cloudflare.com

Files with changes (up to 15)

Original Link	Updated Link
https://developers.cloudflare.com/agents/getting-started/quick-start/	https://agents-callable-es2021-tsconfig-note.preview.developers.cloudflare.com/agents/getting-started/quick-start/
https://developers.cloudflare.com/agents/api-reference/callable-methods/	https://agents-callable-es2021-tsconfig-note.preview.developers.cloudflare.com/agents/api-reference/callable-methods/

[elithrar]

/bonk validate this re: ES2021 tsconfig + decorators, vite, and Workers

[ask-bonk]

Here is my review of this PR:

---

Technical Accuracy: The ES2021 advice is correct

The core claim -- setting "target": "ES2021" in tsconfig.json fixes SyntaxError: Invalid or unexpected token with @callable() -- is technically accurate. Here is the causal chain:

1. The agents SDK uses TC39 standard decorators (not TypeScript's legacy experimentalDecorators). The official cloudflare/agents-starter template ships with experimentalDecorators commented out and "target": "ES2021".
2. Vite uses esbuild for dev server transpilation. When no explicit esbuild.target is set in vite.config.ts, Vite defaults to esnext.
3. At esnext, esbuild passes TC39 decorators through untransformed as native syntax. If the runtime (miniflare/workerd in local dev) does not support native TC39 decorators, you get the SyntaxError.
4. Setting target: ES2021 causes esbuild to downlevel decorators into compatible JavaScript, fixing the error.

ES2021 specifically is the right recommendation -- it matches the official starter template and is more conservative than ES2022 (which would also fix the SyntaxError but leaves class fields native, creating potential decorator/field interaction edge cases).

Content Review

What is good

• Placement is sensible. The note appears in both the callable-methods reference page (where users reading about @callable() would look) and the quick-start troubleshooting section (where users hitting the error during setup would look).
• MDX syntax is clean. The :::note admonition and the ### heading are properly formatted. No unescaped special characters.
• The whitespace/table reformatting in the diff is harmless cosmetic cleanup (column alignment). The trailing newline fix on quick-start.mdx is a good hygiene fix.

What could be improved

1. The note in callable-methods.mdx (line 61-63) is placed oddly. It sits between the "When to use @callable()" table and the "Basic usage" section. This is a general troubleshooting tip interrupting a conceptual flow. It would fit better lower in the page, perhaps near the existing "TypeScript integration" section (line 326), or as a standalone troubleshooting subsection at the bottom before "Next steps."

2. Both notes lack a brief "why." A single clause explaining the mechanism would help users understand and not just cargo-cult the fix. For example:

If you get a SyntaxError: Invalid or unexpected token when starting your dev server, set "target": "ES2021" in your tsconfig.json. This ensures Vite's esbuild transpiler downlevels TC39 decorators instead of passing them through as native syntax.

3. Missing warning about experimentalDecorators. This is the more dangerous pitfall. The agents SDK uses TC39 standard decorators. If a user enables "experimentalDecorators": true (common in older TS projects or Angular-influenced setups), esbuild applies the legacy decorator transform, which is silently incompatible with @callable(). The method would not be registered and calls would fail at runtime with no clear error. Adding a line like:

Do not enable experimentalDecorators in your tsconfig.json. The agents SDK uses TC39 standard decorators.

...would save users from a much harder-to-debug issue than the SyntaxError.

4. Minor style nit. The quick-start troubleshooting heading at line 280 uses the exact error text SyntaxError: Invalid or unexpected token which is good for searchability. Consistent with the existing troubleshooting headings above it.

Verdict

The PR is correct and shippable as-is. The advice works and matches what the official starter template does. The improvements above (explain why, warn about experimentalDecorators, consider note placement) are enhancements that could be done in a follow-up.

github run

[elithrar]

/bonk address the documented improvements, and then re-review for clarity and styleguide. ensure all code is correct.

[ask-bonk]

All improvements have been applied and verified. Here is a summary of the changes:

Changes made

callable-methods.mdx:

1. Moved the troubleshooting note from between the "When to use @callable()" table and "Basic usage" section (where it interrupted the conceptual flow) to a dedicated ## Troubleshooting section before "Next steps" — a much more natural location for this content.

2. Added "why" explanation — the note now explains why ES2021 fixes the issue: "This ensures that Vite's esbuild transpiler downlevels TC39 decorators instead of passing them through as native syntax."

3. Added experimentalDecorators caution — warns users not to enable experimentalDecorators, which would silently apply an incompatible legacy decorator transform and break @callable() at runtime.

4. Added a JSON code example showing the exact tsconfig.json change needed, making it copy-pasteable.

5. Fixed a code bug at line 340 — handleGreet(result: string) had a parameter result that shadowed the const result declaration on the next line. Removed the parameter.

quick-start.mdx:

6. Added "why" explanation — same mechanism explanation as above.

7. Added experimentalDecorators caution — same warning as above.

8. Added a JSON code example — same copy-pasteable tsconfig.json snippet.

Verification

• npm run check passes with 0 errors
• All code examples reviewed and confirmed correct (valid JSON, correct language identifiers, accurate technical claims)
• Style guide compliance verified (active voice, no contractions, sequential headings, no unescaped special characters)

github run