docs: add documentation for defining 2.0 resources & realtime usage patterns#1828
docs: add documentation for defining 2.0 resources & realtime usage patterns#1828viktormarinho merged 1 commit intomainfrom
Conversation
WalkthroughTwo comprehensive documentation guides for DeconfigResource real-time capabilities are added in English and Portuguese. Each guide covers architecture, backend resource definitions, CRUD operations, SSE-based real-time frontend consumption, React Query integration patterns, advanced features, best practices, and API reference documentation. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ 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 decocms-admin-frontend with
|
| Latest commit: |
cb8ec41
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://fbc4c9af.admin-decocms-frontend.pages.dev |
| Branch Preview URL: | https://docs-realtime-resources.admin-decocms-frontend.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: 0
🧹 Nitpick comments (4)
docs/view/src/content/pt-br/guides/deconfig-realtime.mdx (4)
18-18: Address locale violations: replace English technical terms with Portuguese equivalents.Static analysis has flagged several instances where English words should be replaced with Portuguese:
- Line 18: "Server-Sent Events" → Consider "Eventos Enviados pelo Servidor" (already correct in context, but used alongside Portuguese)
- Line 26:
server/tools/index.tsis a code path and should remain as-is- Line 182: "Server-Sent Events" → Keep English for technical specification names (this is correct)
- Line 648: "Performance" → Replace with "Desempenho" or "Atuação"
- Line 740: "Server-Sent Events" in link text → Keep English for official specification names
The alerts conflate code paths with natural language. However, line 648 does warrant attention: "Otimização de Performance" should be "Otimização de Desempenho" for better Portuguese style, unless this is a deliberate choice to preserve the English term as a technical label.
- ### Otimização de Performance + ### Otimização de DesempenhoAlso applies to: 26-26, 182-182, 648-648, 740-740
509-509: Simplify conjunction for better Portuguese flow.Static analysis suggests the sentence can be more concise by removing the redundant "que" pronoun.
- A melhor prática é disparar notificações de sincronização diretamente das suas tools backend que modificam dados externos. Isso garante consistência e que todos os clientes sejam notificados. + A melhor prática é disparar notificações de sincronização diretamente das suas tools backend que modificam dados externos. Isso garante consistência e notifica todos os clientes.
694-694: Remove duplicate punctuation.Static analysis detected duplicate punctuation. Verify and correct if present.
Retorna: (ensure only one colon, not two)
725-725: Replace "template" with Portuguese equivalent.Line 725 uses "template" where "modelo" would be more appropriate for Portuguese.
- 2. Verifique se o formato do template URI corresponde a `rsc://{integrationId}/{resourceName}/*` + 2. Verifique se o formato do modelo URI corresponde a `rsc://{integrationId}/{resourceName}/*`
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs/view/src/content/en/guides/deconfig-realtime.mdx(1 hunks)docs/view/src/content/pt-br/guides/deconfig-realtime.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/deconfig-realtime.mdxdocs/view/src/content/pt-br/guides/deconfig-realtime.mdx
🪛 LanguageTool
docs/view/src/content/pt-br/guides/deconfig-realtime.mdx
[locale-violation] ~18-~18: “Server” é um estrangeirismo. É preferível dizer “servidor”.
Context: ...) - Sincronização em tempo real via Server-Sent Events (SSE) - **URIs padronizadas...
(PT_BARBARISMS_REPLACE_SERVER)
[locale-violation] ~26-~26: “server” é um estrangeirismo. É preferível dizer “servidor”.
Context: ...de recurso no seu arquivo de tools (ex: server/tools/index.ts). O schema de dados é d...
(PT_BARBARISMS_REPLACE_SERVER)
[uncategorized] ~84-~84: Se é uma abreviatura, falta um ponto. Se for uma expressão, coloque entre aspas.
Context: ...esource e executar a geração de código (deco gen ou equivalente), as seguintes tools MC...
(ABREVIATIONS_PUNCTUATION)
[locale-violation] ~182-~182: “Server” é um estrangeirismo. É preferível dizer “servidor”.
Context: ...vo em todos os clientes conectados, use Server-Sent Events: ```typescript import { us...
(PT_BARBARISMS_REPLACE_SERVER)
[style] ~509-~509: Pode omitir o pronome ‘que’ para tornar o texto mais fluido.
Context: ...dos externos. Isso garante consistência e que todos os clientes sejam notificados. `...
(SIMPLIFICAR_E_QUE_E)
[locale-violation] ~648-~648: “Performance” é um estrangeirismo. É preferível dizer “desempenho”, “atuação”, “apresentação”, “espetáculo” ou “interpretação”.
Context: ...to ocorreu } } ``` ### Otimização de Performance - Use pageSize: Infinity apenas quan...
(PT_BARBARISMS_REPLACE_PERFORMANCE)
[uncategorized] ~694-~694: Pontuação duplicada
Context: ...oid>, }) ``` Retorna: Um objeto com: - create(env): Função para criar as tools do resource ...
(DOUBLE_PUNCTUATION_XML)
[locale-violation] ~725-~725: “template” é um estrangeirismo. É preferível dizer “modelo”.
Context: ...meválido 2. Verifique se o formato do template URI corresponde arsc://{integrationId...
(PT_BARBARISMS_REPLACE_TEMPLATE)
[typographical] ~738-~738: Símbolo sem par: “[” aparentemente está ausente
Context: ...- [Especificação do Padrão Resources 2.0](https://github.com/deco-cx/chat/blob/ma...
(UNPAIRED_BRACKETS)
[locale-violation] ~740-~740: “Server” é um estrangeirismo. É preferível dizer “servidor”.
Context: ...ntação Zod](https://zod.dev) - [Guia de Server-Sent Events (SSE)](https://developer.mo...
(PT_BARBARISMS_REPLACE_SERVER)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Cloudflare Pages
🔇 Additional comments (21)
docs/view/src/content/en/guides/deconfig-realtime.mdx (13)
1-58: Well-structured frontmatter, imports, and opening example.The English guide opens clearly with frontmatter, component import, and a compelling overview statement. The example Theme Settings resource is well-chosen and demonstrates the full resource definition flow. The numbered comments guide readers through each step effectively.
60-78: Configuration options section is clear and comprehensive.Covers required fields (
dataSchema,resourceName), optional customizations, and advanced features like custom validation. The optional semanticvalidatefunction is well-documented.
86-99: CRUD operations matrix is well-organized.The table clearly maps operations to MCP tool names and descriptions. The Callout explaining the
{NAME}uppercase transformation is helpful for avoiding confusion.
101-131: Resource URI format and search parameters are thorough.The
rsc://format is clearly explained with concrete examples. Search parameters documentation covers filtering, sorting, pagination, and includes sensible defaults (page: 1, pageSize: 10).
136-178: Basic CRUD operations are well-documented with practical examples.Each operation (Create, Read, Update, Delete, Search) includes a concise code snippet showing the proper client method call and parameter structure. Comments clarify merge behavior for updates.
180-239: SSE integration example is practical and addresses connection lifecycle.Shows how to get watch endpoint, construct SSE URL with URI template, handle messages, and properly clean up EventSource. Error handling is included. Good pedagogical flow from basic to complete.
241-324: Complete React Query integration example is production-ready.Demonstrates useQuery for data fetching, useMutation for CRUD operations, proper cache invalidation patterns, and real-time SSE subscription. State is managed coherently across multiple hooks. Error handling within setupSSE is present.
328-361: Advanced features section covers practical extension points.Custom validation, custom storage directory, and specific resource watching are well-explained with concise examples. These are the most common customization needs.
363-504: External data signaling pattern is innovative and well-documented.The Airtable integration example clearly demonstrates using DeconfigResource as a signal mechanism for external data sources. Multi-step breakdown (define resource, create trigger tool, frontend hook, usage patterns) is logical and easy to follow. Benefits list aligns well with the documented pattern.
607-660: Best practices section addresses real-world concerns.Resource naming conventions, schema design guidance with
.describe(), error handling with specific error types, and performance optimization all reflect practical experience. ThestaleTimeconfiguration example is concrete.
662-674: SSE connection management best practices are appropriate.Covers EventSource cleanup, error handling, and reconnection strategy. Suggestion to use single SSE connection for multiple resource types is pragmatic for connection pooling.
678-707: API reference section is concise but complete.Both
DeconfigResource.define()andDeconfigResource.watchAPI()are documented with signatures, key methods/returns, and purpose. Appropriate level of detail for a reference.
710-747: Troubleshooting section addresses common pain points.Three scenarios (missing module, SSE connection fails, resource not found) with diagnostic steps and solutions. Links to external documentation (Resources 2.0, Zod, SSE, React Query) are valuable for deeper learning.
docs/view/src/content/pt-br/guides/deconfig-realtime.mdx (8)
1-21: Portuguese translation maintains structural fidelity to English version.Frontmatter, imports, and opening overview are well-translated. Technical terms are appropriately preserved or localized (e.g., "schema" remains "schema", "Resources 2.0" becomes "Resources 2.0").
738-738: Verify link formatting for unpaired brackets.Static analysis flagged an unpaired bracket at line 738. This is likely a false positive for Markdown link syntax, but verify the link is correctly formatted.
Current:
[Especificação do Padrão Resources 2.0](https://github.com/deco-cx/chat/blob/main/packages/runtime/src/bindings/resources/bindings.ts)This appears correct. The static analysis hint may be a false positive due to LanguageTool not fully understanding Markdown syntax.
1-100: Portuguese translation is comprehensive and accurate.The opening sections (frontmatter through CRUD operations matrix) faithfully translate the English guide while maintaining Portuguese language conventions. Technical terms are appropriately handled.
101-240: Real-time consumption section is well-translated.URI format, search parameters, basic CRUD operations, and SSE integration examples maintain clarity and accuracy. Portuguese technical language is appropriate and consistent.
241-325: React Query integration example maintains production-quality in Portuguese.All comments, variable names, and code structures are translated meaningfully while preserving technical precision. Examples remain practical and implementable.
328-504: Advanced features and external data signaling sections are thorough.Airtable integration example is well-adapted to Portuguese with clear step-by-step guidance. The multi-language code examples work because code syntax remains consistent; Portuguese comments clarify intent effectively.
607-660: Best practices translated appropriately with localization context.Resource naming, schema design, error handling, and performance optimization guidance is contextualized for Portuguese developers. The examples and explanations are clear and actionable.
662-747: SSE management, API reference, troubleshooting, and resources sections are complete.Final sections maintain parity with English version. Links to external resources (Zod, MDN, React Query, etc.) remain valid. Closing encouragement ("Bora construir! 🚀") adds local flavor appropriately.
1 participant
Summary by CodeRabbit