refactor: update docs #1595
refactor: update docs #1595
Conversation
…I app development - Revised the "Getting Started" guide to reflect changes in app creation and deployment processes. - Enhanced the "Introduction" section to clarify deco's capabilities as a full-stack TypeScript platform. - Updated project structure documentation to emphasize the integration of backend and frontend components. - Added new guides for CLI commands, resources, integrations, security, and self-hosting to improve developer experience. - Improved existing guides on building views and workflows to provide clearer instructions and examples. These changes aim to streamline the onboarding process and enhance the overall clarity of the documentation for new users.
WalkthroughThis PR comprehensively updates Deco's documentation to reflect a full-stack, monorepo-based development model. Multiple guides are rewritten to shift emphasis from MCP-centric workflows to unified backend/frontend TypeScript applications with typed RPC, including new sections on self-hosting, resources, security, and CLI operations, plus expanded deployment, integration, and tool-creation guidance with concrete code examples. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~35 minutes The PR spans 10+ documentation files with heterogeneous, narrative-focused changes. While primarily textual, the updates require verification of example code accuracy, consistency of messaging across guides, logical flow of new sections, and alignment with platform capabilities. Several files (creating-tools.mdx, self-hosting.mdx, project-structure.mdx) are substantive, requiring careful attention to detail. Possibly related PRs
Suggested reviewers
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Deploying chat with
|
| Latest commit: |
7f7fede
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://66fac2b3.chat-46r.pages.dev |
| Branch Preview URL: | https://feat-cecilia-docs.chat-46r.pages.dev |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/view/src/content/en/guides/creating-tools.mdx (1)
155-182: Database insert operation syntax appears incorrect.The database operation example (lines 155-182) shows:
await db .insert({ name: customersTable.name, cpf: customersTable.cpf, city: customersTable.city, state: customersTable.state, }) .into(customersTable) .returning({ id: customersTable.id });This doesn't match standard Drizzle ORM syntax. The
.insert()method should accept a table first, then either.values()or column assignments. The current example appears to mix patterns or use non-existent methods.The correct Drizzle ORM pattern should be:
const result = await db .insert(customersTable) .values({ name: context.name, cpf: context.cpf, city: context.city, state: context.state, }) .returning({ id: customersTable.id }); return { id: result[0].id };Verify the actual Drizzle API and correct the example to match. This is a critical fix for users copying this pattern.
🧹 Nitpick comments (12)
docs/view/src/content/en/guides/security-and-permissions.mdx (1)
218-360: Add error handling guidance to security best practices.The code examples in this section show happy-path patterns but omit error handling. Adding try-catch blocks or error response examples would make the patterns more production-ready and prevent developers from shipping unhandled errors that could leak sensitive information.
For example, in the audit logging pattern (lines 277-295), show what happens if the delete succeeds but audit logging fails.
docs/view/src/content/en/guides/self-hosting.mdx (1)
315-335: Document pricing claims carefully for different scales.Lines 317–335 provide cost estimation tables and examples. The table and usage examples are helpful, but the claim at line 331 ("Most deco apps run for $5-20/month even at production scale") should be verified against current Cloudflare pricing. Consider adding a note that pricing may vary based on actual usage patterns and request volume.
Consider adding a disclaimer such as:
<Callout type="info"> **Pricing varies by usage**: The examples above assume typical application patterns. Actual costs depend on request volume, CPU time, database operations, and data stored. Test your app's resource usage in development to estimate costs accurately. </Callout>This helps set expectations without overpromising.
docs/view/src/content/en/guides/integrations.mdx (1)
117-210: Comprehensive but dense integration catalog.Lines 117–210 provide an exhaustive list of Global and Project-scoped integrations (TEAMS_, MEMBER_, AGENTS_*, etc.). While completeness is valuable, the sheer volume may overwhelm readers. Consider this approach to improve scannability:
Break up the integration categories into collapsible sections or link to a reference table. For example:
### Global Integrations Accessible at the organization/team level: **[expand] Team Management** (5 tools) **[expand] User & Member Management** (3 tools) **[expand] Integration Management (Global)** (3 tools) → [View full reference](/reference/integrations) for complete API listThis reduces cognitive load in the guide while keeping the full catalog available in a dedicated reference page.
docs/view/src/content/en/guides/cli-commands.mdx (1)
204-393: Deconfig (synchronization) section is comprehensive but could be condensed.Lines 204–393 document the Deconfig sync system in detail: clone, push (with watch/dry-run), pull, list, watch, get, put, delete. The content is well-organized and examples are clear. However, the section is lengthy (190 lines). Consider this optional refactor:
Summary table at the beginning of the Deconfig section to help readers quickly find the command they need:
### Quick Command Reference | Command | Purpose | |---------|---------| | `deco deconfig clone` | Download remote branch | | `deco deconfig push` | Upload local changes | | `deco deconfig pull` | Download remote changes | | `deco deconfig list` | Browse remote files | | `deco deconfig watch` | Monitor for changes | | `deco deconfig get` | Download single file | | `deco deconfig put` | Upload single file | | `deco deconfig delete` | Delete remote file |This gives readers a quick mental map before diving into detailed examples.
docs/view/src/content/en/project-structure.mdx (3)
229-241: Clarify workflow creation syntax in example.The workflow example uses
.then(step).commit()chaining without showing the complete or most idiomatic pattern. For someone unfamiliar with this API, it's unclear whethercreateWorkflowreturns a builder, what.then()does precisely, or whether this is the recommended pattern.Consider expanding the example or linking to a more detailed guide:
const createMyWorkflow = (env: Env) => { const step = createStepFromTool(createMyTool(env)); return createWorkflow({ id: "MY_WORKFLOW", inputSchema: z.object({ name: z.string() }), outputSchema: z.object({ message: z.string() }), }) .then(step) // Chain the step .commit(); // Finalize the workflow };Add a brief explanation: "The workflow builder
.then()chains steps, and.commit()finalizes the workflow definition."
9-13: Clarify the "no REST APIs" claim with appropriate context.Line 12 states "No REST APIs, no OpenAPI specs, no integration layer". While the typed RPC approach eliminates hand-written REST endpoints, the underlying HTTP transport still exists (RPC over HTTP). This might mislead readers into thinking there's no HTTP layer at all.
Refine the messaging:
**Key advantage**: Changes to backend tools automatically flow to your frontend through typed RPC. No hand-written REST endpoints, no separate OpenAPI specs, no integration layer—the RPC client calls your backend tools directly over HTTP with full TypeScript type safety.This clarifies that HTTP is still the transport, but developers don't write traditional REST APIs.
358-393: "Standard RPC Client" heading may cause confusion.Line 358 uses "Standard RPC Client" as a heading, but lines 395-407 introduce "Logged RPC Client (Debugging)". This suggests there are multiple RPC client types to choose from, which could confuse beginners about which one to use.
Rename line 358 heading to clarify:
### Typed RPC Client (Standard)And adjust the subsequent heading for clarity:
### Logged RPC Client (For Debugging)Or add a brief note under line 358 explaining this is the default/recommended approach.
docs/view/src/content/en/guides/building-views.mdx (2)
147-150: Webhooks mentioned but not explained or linked.Line 147-149 introduces webhooks as an alternative for long-running workflows: "For long-running workflows, use webhooks instead of polling." However, no guidance is provided on how to set up webhooks, what format they use, or where to find that documentation.
Either expand with basic webhook setup guidance or add a link to the webhooks documentation. For example:
<Callout type="tip"> **Alternative**: For long-running workflows, use webhooks instead of polling. See [Webhooks Guide](/en/guides/webhooks) for setup instructions. </Callout>Or add a brief code example showing webhook registration.
95-97: Clarify RPC routing detail for clarity.Line 95-97 states: "The RPC client makes HTTP requests to your Cloudflare Worker at
/mcp. The Worker routes them to the appropriate tool/workflow."This is slightly misleading—the
/mcpendpoint is the MCP server interface, not necessarily where RPC requests are routed. Depending on implementation, RPC might route differently.Refine for precision:
**Behind the scenes**: The RPC client makes HTTP requests to your Cloudflare Worker. The Worker routes them to the appropriate tool/workflow handler. Both the MCP server (at `/mcp`) and RPC client use the same underlying tool definitions.docs/view/src/content/en/getting-started.mdx (1)
231-254: Development workflow section could clarify command purpose.Lines 231-254 list commands, but the
deco addcommand at line 249 lacks explanation of what it does in this context (adding integrations).Add a brief comment above or beside the command:
# Add integrations (Gmail, Slack, etc.) deco addThis clarifies the command's purpose for new developers.
docs/view/src/content/en/guides/creating-tools.mdx (2)
450-454: Environment variable syntax not cross-platform.Line 453 shows Unix/Linux shell syntax for setting environment variables:
DECO_SELF_URL=https://localhost-abc123.deco.host/mcp npm run gen:selfThis will fail on Windows CMD or PowerShell without modification.
Provide cross-platform guidance:
### Generate Type-Safe RPC Client Before creating views, generate types for your tools: **macOS/Linux:** ```bash DECO_SELF_URL=https://localhost-abc123.deco.host/mcp npm run gen:self ``` **Windows (Command Prompt):** ```cmd set DECO_SELF_URL=https://localhost-abc123.deco.host/mcp && npm run gen:self ``` **Windows (PowerShell):** ```powershell $env:DECO_SELF_URL='https://localhost-abc123.deco.host/mcp'; npm run gen:self ``` Or use a tool like `cross-env` in your npm scripts for universal support.
549-569: Authentication example uses undefineduseAuthhook.The authentication section (lines 549-569) uses a
useAuthhook imported at line 551:import { useAuth } from "./hooks/useAuth";However, this hook is not defined or explained in the guide. Readers may not understand where this comes from or how to implement it.
Either:
- Provide a brief
useAuthhook implementation example, or- Link to authentication documentation, or
- Note that the hook should be implemented using the deco OAuth pattern
For example, add a note:
// useAuth should handle OAuth flow via deco runtime // See [Authentication Guide](/en/guides/authentication) for implementation export function useAuth() { ... }
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (14)
docs/view/src/content/en/getting-started.mdx(1 hunks)docs/view/src/content/en/guides/building-views.mdx(2 hunks)docs/view/src/content/en/guides/building-workflows.mdx(2 hunks)docs/view/src/content/en/guides/cli-commands.mdx(1 hunks)docs/view/src/content/en/guides/creating-tools.mdx(2 hunks)docs/view/src/content/en/guides/deployment.mdx(1 hunks)docs/view/src/content/en/guides/integrations.mdx(1 hunks)docs/view/src/content/en/guides/resources.mdx(1 hunks)docs/view/src/content/en/guides/security-and-permissions.mdx(1 hunks)docs/view/src/content/en/guides/self-hosting.mdx(1 hunks)docs/view/src/content/en/introduction.mdx(1 hunks)docs/view/src/content/en/project-structure.mdx(6 hunks)docs/view/src/content/en/reference/faq.mdx(1 hunks)docs/view/src/content/en/reference/resources.mdx(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
docs/**
📄 CodeRabbit inference engine (AGENTS.md)
Store long-form documentation under docs/
Files:
docs/view/src/content/en/guides/cli-commands.mdxdocs/view/src/content/en/reference/resources.mdxdocs/view/src/content/en/guides/security-and-permissions.mdxdocs/view/src/content/en/guides/deployment.mdxdocs/view/src/content/en/guides/self-hosting.mdxdocs/view/src/content/en/reference/faq.mdxdocs/view/src/content/en/guides/resources.mdxdocs/view/src/content/en/guides/building-views.mdxdocs/view/src/content/en/guides/integrations.mdxdocs/view/src/content/en/getting-started.mdxdocs/view/src/content/en/introduction.mdxdocs/view/src/content/en/guides/creating-tools.mdxdocs/view/src/content/en/guides/building-workflows.mdxdocs/view/src/content/en/project-structure.mdx
🧠 Learnings (5)
📚 Learning: 2025-09-26T00:32:16.621Z
Learnt from: CR
PR: deco-cx/chat#0
File: .cursor/rules/structure.mdc:0-0
Timestamp: 2025-09-26T00:32:16.621Z
Learning: Use React 19 for the decocms admin web app UI
Applied to files:
docs/view/src/content/en/guides/building-views.mdx
📚 Learning: 2025-09-02T14:01:08.273Z
Learnt from: CR
PR: deco-cx/chat#0
File: docs/.cursor/rules/main.mdc:0-0
Timestamp: 2025-09-02T14:01:08.273Z
Learning: Applies to docs/server/main.ts : Define new MCP tools in `server/main.ts`
Applied to files:
docs/view/src/content/en/project-structure.mdx
📚 Learning: 2025-09-02T13:56:59.909Z
Learnt from: CR
PR: deco-cx/chat#0
File: .cursor/rules/data-flow.mdc:0-0
Timestamp: 2025-09-02T13:56:59.909Z
Learning: Applies to **/*.{ts,tsx} : Group related tools into typed collections (e.g., GLOBAL_TOOLS, WORKSPACE_TOOLS) and export them as const
Applied to files:
docs/view/src/content/en/project-structure.mdx
📚 Learning: 2025-09-02T14:01:08.273Z
Learnt from: CR
PR: deco-cx/chat#0
File: docs/.cursor/rules/main.mdc:0-0
Timestamp: 2025-09-02T14:01:08.273Z
Learning: Applies to docs/server/main.ts : Define new workflows in `server/main.ts`
Applied to files:
docs/view/src/content/en/project-structure.mdx
📚 Learning: 2025-09-02T14:01:08.273Z
Learnt from: CR
PR: deco-cx/chat#0
File: docs/.cursor/rules/main.mdc:0-0
Timestamp: 2025-09-02T14:01:08.273Z
Learning: Applies to docs/server/main.ts : Include newly created workflows in the `withRuntime` `workflows` array in `server/main.ts`
Applied to files:
docs/view/src/content/en/project-structure.mdx
🪛 LanguageTool
docs/view/src/content/en/guides/cli-commands.mdx
[grammar] ~281-~281: Ensure spelling is correct
Context: ... and pushes changes automatically (with 500ms debounce). #### Dry Run See what woul...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🔇 Additional comments (25)
docs/view/src/content/en/reference/resources.mdx (3)
1-5: LGTM – Front matter is properly formatted.The YAML front matter contains appropriate metadata for a documentation page (title, description, icon).
25-27: Clarification added to Cloudflare Workers section.The change adds helpful context explaining why Cloudflare Workers is relevant to deco developers. This is a minor but useful improvement to the reference material.
7-36: Well-organized reference page with categorized resources.The page effectively groups resources into logical sections (Core Documentation, Framework, Examples, Infrastructure, Community, Additional Resources) and provides brief descriptions for each link. The content is appropriate for a reference/links page.
docs/view/src/content/en/guides/security-and-permissions.mdx (5)
27-54: Complete the OAuth authentication flow example with token handling.The
useAuthhook shows redirecting to/oauth/startbut doesn't explain how the token is returned to the app or where it's stored. Visitors won't understand the complete flow (redirect, authentication, callback, token storage).Expand the example to show:
- How the OAuth callback is handled (e.g.,
/oauth/callback?token=...)- Where/how the token is stored (localStorage, session, etc.)
- How the token is included in subsequent requests
export function useAuth() { const [user, setUser] = useState(null); const login = () => { const returnUrl = encodeURIComponent(window.location.href); window.location.href = `/oauth/start?returnUrl=${returnUrl}`; }; const logout = () => { // Clear session fetch("/oauth/logout", { method: "POST" }); setUser(null); }; useEffect(() => { // Check if user is authenticated fetch("/api/me") .then((res) => res.json()) .then(setUser) .catch(() => setUser(null)); }, []); return { user, login, logout }; }Could you verify how the OAuth token flows back to the client and clarify the callback handling? Is there an example elsewhere in the docs that shows the complete redirect flow?
134-160: Clarify runtime-provided parameters increateToolexamples.The code examples use
context,workspace, anduserparameters without documenting their origin. Readers won't understand which parameters are validated inputs vs. auto-provided by the Deco runtime.Expand the example or add a note explaining:
context= validated input from the Zod schemaworkspace= automatically injected workspace IDuser= automatically injected user/caller identityThis will help developers understand the full API contract.
303-326: Document @upstash setup or provide a built-in alternative.The rate limiting example imports
@upstash/ratelimitwithout showing installation, configuration, or environment setup. Developers following this guide will encounter missing dependencies.Either:
- Show
npm install @upstash/ratelimit @upstash/redisand wrangler configuration- Mention if Deco provides a built-in rate limiting utility
- Link to Upstash setup documentation
72-78: Verify the API endpoint for programmatic access.The curl example uses
/mcp/tools/call/SEND_EMAIL, but the PR shifts from MCP-centric to unified RPC-based architecture. Confirm this endpoint is still current or update to reflect the new API structure.
1-470: Overall: Comprehensive and well-structured security guide.The documentation covers OAuth, RBAC, bindings, and security best practices with clear examples and anti-patterns. The security checklist and testing guidance are practical and actionable. The examples align well with the PR's emphasis on type-safe, full-stack RPC-based architecture.
A few documentation gaps (OAuth callback, @upstash setup, runtime parameters) need clarification, but the core security patterns are sound and appropriate for this platform.
docs/view/src/content/en/guides/self-hosting.mdx (1)
1-50: Comprehensive self-hosting guide with clear structure.The overall organization is excellent: architecture overview, prerequisites, deployment options (CLI, Wrangler, GitHub Actions), configuration, database management, monitoring, security, cost estimation, scaling, troubleshooting, and migration guidance are all well-sequenced. Code examples are concrete and helpful. The use of Callouts (success, info, warning) effectively highlights key points.
docs/view/src/content/en/guides/integrations.mdx (1)
9-26: Context Mesh framing is clear and well-motivated.Lines 9–26 introduce the Context Mesh concept effectively. The Callout at lines 11–13 clearly articulates the value proposition (unified access, no credential sprawl, built-in RBAC/audit trails). The explanation in lines 15–25 reinforces how it differs from traditional integrations.
docs/view/src/content/en/introduction.mdx (2)
1-20: Effective reframing as a full-stack platform with clear value proposition.The new introduction establishes a compelling narrative arc:
- Hero message (line 9–11): Full-stack TypeScript platform with unified deployment
- Problem/solution (lines 15–17): Avoids the "months of integration work" trap
- Target audience (lines 21–25): Practical segmentation for different user types
The messaging is consistent with broader PR changes (full-stack, single codebase, typed RPC, production-ready).
129-142: Inverted checklist effectively reinforces platform completeness.Lines 129–142 use a clever rhetorical device—listing what you don't need to build—to reinforce that deco handles common concerns (auth, RBAC, RPC, observability, deployment). This is a strong persuasion technique that works well in marketing copy.
docs/view/src/content/en/reference/faq.mdx (1)
10-147: Well-organized FAQ with practical examples and clear categorization.The reorganization into General, Development, Technical, Integration, and Troubleshooting sections makes the FAQ more navigable. Each question includes concrete examples (code snippets, step-by-step instructions, CLI commands) that help readers unblock themselves quickly. The cross-references to related guides (e.g., "See Creating Tools") are helpful.
docs/view/src/content/en/guides/resources.mdx (2)
1-50: Comprehensive Resources guide with clear progression from concept to implementation.The guide progresses logically:
- Concept (lines 9–25): What Resources are, their purpose, URI structure
- URI format (lines 27–40): Concrete spec with examples
- Creation (lines 42–72): Schema definition and tool generation
- Operations (lines 73–147): Complete CRUD examples
The pedagogical approach is strong—each section builds on the previous one, and code examples are practical and runnable.
349-374: Best practices section covers essential concerns concisely.Lines 349–374 address schema design, naming conventions, performance (pagination, caching, indexes), and security (validation, RBAC, input sanitization). These are the right considerations for a data resource guide.
docs/view/src/content/en/guides/cli-commands.mdx (2)
100-104: Preview URL feature well-explained with practical example.Line 100 introduces the publicly accessible preview URL with helpful context: "The CLI also provides a publicly accessible preview URL (e.g.,
https://localhost-abc123.deco.host)". The Callout at lines 102–104 explains the benefit (testing integrations, sharing with team).
462-522: Common workflows section provides excellent end-to-end guidance.Lines 462–522 document four critical workflows:
- Initial setup (lines 464–480): Login → create → install → dev
- Development loop (lines 482–496): Edit → gen → use pattern
- Deployment (lines 498–509): Local test → deploy → verify
- Collaboration (lines 511–522): Push/pull workflow for multiple developers
These real-world scenarios help readers understand how to use individual commands in context.
docs/view/src/content/en/guides/building-workflows.mdx (3)
15-40: Dual creation paths (UI and code) serve different skill levels well.Lines 15–40 introduce workflow creation in two ways:
- UI-based (no-code): Using the CMS copilot to define workflows interactively
- Code-based (full control): TypeScript with
createWorkflow, step chaining, control flowThis dual approach is pedagogically strong—users can start with the UI for rapid prototyping, then graduate to code for complex logic. The Callout at lines 32–34 provides a practical pro-tip for copilot usage.
183-278: Clear three-step workflow registration and React integration pattern.Lines 183–278 document how to integrate workflows into React UIs:
- Define (lines 187–219): Schema, steps, commit
- Register (lines 221–230): Add to workflows array
- Call (lines 232–273): Async RPC call with
.start()and.waitForCompletion()The React example includes proper state management (loading, result), error handling (try/finally), and async flow. The Callout at lines 275–277 clarifies that workflows run asynchronously in the background.
279-327: Hybrid approach (agents + workflows) demonstrates powerful pattern.Lines 279–327 show how to combine adaptive agents with deterministic workflows:
- Agent step: Analyzes unstructured input (customer message), extracts intent
- Deterministic steps: Routes based on category, sends notifications
The "Best of both worlds" Callout (lines 314–316) articulates the value: agents handle reasoning, workflows ensure predictability. The "When to Use Each" table (lines 318–327) provides clear guidance.
docs/view/src/content/en/guides/deployment.mdx (3)
1-25: Simplified one-command deployment messaging is clear and compelling.Lines 1–25 reframe deployment from a multi-step process to a single command. The success Callout at lines 11–13 articulates the key value: no separate frontend/backend deployments, no CORS configuration, no environment synchronization. This aligns with the full-stack narrative of the broader PR.
152-188: Post-deployment verification checklist is practical and comprehensive.Lines 152–188 provide a three-step post-deployment checklist:
- Test the UI (lines 156–167): Open the URL, verify UI loads and tools/workflows work
- Test the MCP server (lines 169–177): Add to admin dashboard, test tools in chat
- Verify integrations (lines 179–188): Check OAuth, API keys, rate limits
This is well-structured practical guidance that helps users catch issues before going to production. The Warning Callout about environment-specific configs (lines 186–188) is important and often overlooked.
255-291: GitHub Actions CI/CD example is well-documented with security best practices.Lines 255–291 show a realistic GitHub Actions workflow that:
- Triggers on pushes to main
- Sets up Node.js
- Installs dependencies
- Deploys with API token
The Callout at lines 289–291 reminds users to generate tokens and store them as secrets—important security guidance. The use of
${{ secrets.DECO_API_TOKEN }}shows proper secret handling.docs/view/src/content/en/getting-started.mdx (1)
125-147: Tool example uses incorrect execute pattern.In the greeting tool example (lines 128-147), the
executefunction signature and context usage appears inconsistent with patterns shown elsewhere.The code shows:
execute: async ({ context }) => { const greetings = { en: `Hello, ${context.name}!`, ... }; return { greeting: greetings[context.language] }; }However, based on typical tool creation patterns, the context object should contain the parsed input fields directly. If
inputSchemadefinesnameandlanguagefields, they should be accessed ascontext.nameandcontext.language. This example looks correct, but it's unclear if this matches the actualcreateToolAPI signature used in the runtime.Verify that the
executefunction receives context with input schema fields directly accessible as shown, or clarify the destructuring pattern if it differs. Consider checking the actual@deco/workers-runtimeimplementation or adding a comment explaining the pattern:execute: async ({ context }) => { // context contains the validated input schema fields // { name: string, language: "en" | "es" | "pt" } const greetings = { en: `Hello, ${context.name}!`, ... } }docs/view/src/content/en/guides/creating-tools.mdx (1)
268-321: EmailForm component example matches building-views patterns well.The EmailForm component (lines 268-321) correctly demonstrates:
- Importing the typed RPC client
- Using type-safe tool calls with autocomplete
- Loading state management
- Error handling with try/catch
- Consistent with building-views.mdx examples
This example is well-structured and provides a clear, practical demonstration of tool usage in React. The pattern matches best practices shown in other guides.
| auth: { | ||
| providers: ["google", "github"], | ||
| allowedDomains: ["yourdomain.com"], // Restrict signups | ||
| }, | ||
| rbac: { |
There was a problem hiding this comment.
🧩 Analysis chain
Verify Cloudflare Wrangler --region flag support.
Line 281 uses wrangler deploy --region eu and wrangler deploy --region us, but Cloudflare Workers deploy globally by design—the --region flag may not exist or work as documented. Wrangler typically routes to the nearest data center automatically based on request location.
🌐 Web query:
Does Cloudflare Wrangler CLI support the --region flag for Workers deployment?
💡 Result:
Short answer: No — Wrangler's deploy command does not support a general --region flag for Workers. Wrangler deploy is documented without a --region option; region control for Workers is handled via features like Regional Services / regional hostnames (dashboard or API), Smart Placement, or the compliance_region setting (e.g., FedRAMP) in config or env vars. [1][2][3]
Sources:
- Wrangler deploy command docs (options list — no --region). [1]
- Cloudflare Data Localization / Regional Services for Workers (regional_hostnames via dashboard/API). [2]
- Wrangler release notes: compliance_region (FedRAMP) support via config or CLOUDFLARE_COMPLIANCE_REGION (not a deploy --region flag). [3]
Remove unsupported --region flag from deployment examples.
Wrangler's deploy command does not support a --region flag for Workers deployment. Lines 281-282 show wrangler deploy --region eu and wrangler deploy --region us, which are not valid Wrangler syntax and will fail when executed.
Replace these with the correct approach: region control for Workers is handled via Regional Services/regional hostnames (dashboard or API), Smart Placement, or the compliance_region setting in config. Either remove the --region flags or update the examples to use the correct region configuration method.
🤖 Prompt for AI Agents
In docs/view/src/content/en/guides/self-hosting.mdx around lines 280 to 284, the
deployment examples incorrectly use the unsupported Wrangler CLI flag `--region`
(e.g., `wrangler deploy --region eu`), which will fail; remove the `--region`
flags from these examples and either omit region specification altogether or
replace with a short note pointing readers to the supported methods (Cloudflare
dashboard/API regional hostnames, Smart Placement, or the compliance_region
setting in wrangler/config) so examples use valid Wrangler syntax.
cecilia-marques
changed the title
…I app development
These changes aim to streamline the onboarding process and enhance the overall clarity of the documentation for new users.
What is this contribution about?
Screenshots/Demonstration
Review Checklist
Summary by CodeRabbit