docs: corrections and pitfalls from AI builder field notes#6775
docs: corrections and pitfalls from AI builder field notes#6775amsraman wants to merge 1 commit into
Conversation
Upstreams doc gaps found while reconciling Reflex Build's curated knowledge base against these pages: - upload: rx.get_upload_url returns a frontend Var, not str (bug fix); upload id must be a literal; handler/trigger placement pitfalls; uploading-from-a-form guidance; avoid hardcoding /_upload/ paths - drag-and-drop: memo params are Vars; on_drag_start unsupported; nested drop dedupe + root-level drops; collected-params naming with _collected_params example; don't add a second provider - shared_state: token sanitization; _link_to pitfalls; computed var placement - lifespan_tasks: lifespan task vs background event decision guidance - markdown: escaping literal dollar signs (LaTeX delimiter) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Merging this PR will not alter performance
Comparing 
Footnotes
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 021e99e9f3
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - **Type**: Returns `str` | ||
| - **Type**: Returns a frontend `Var` (a JavaScript expression), not a Python `str` | ||
|
|
||
| Because it returns a frontend Var, `rx.get_upload_url` is frontend-only: use it in component code and event triggers, not in backend event handlers or computed vars, where the value would not resolve to a usable string. If you genuinely need the upload URL as a plain string on the backend, construct it from `self.router.headers.host` instead. |
There was a problem hiding this comment.
When users follow this backend fallback in deployments with backend_path or a separately served API, building from self.router.headers.host omits the configured upload prefix and scheme that get_upload_url gets from getBackendURL(env.UPLOAD) and that the server mounts via config.prepend_backend_path(str(Endpoint.UPLOAD)). This can produce links that work locally but 404 in prefixed/split frontend-backend deployments; point backend-only examples at the configured upload endpoint (for example Endpoint.UPLOAD.get_url() plus the filename) instead of the Host header.
Useful? React with 👍 / 👎.
Greptile SummaryThis PR backfills five documentation pages with pitfall callouts and corrections sourced from Reflex Build's AI builder knowledge base, consolidating hard-won field notes into the official docs.
Confidence Score: 4/5Safe to merge — all changes are documentation-only and correct real gaps or errors with no behavioral changes to library code. The content is accurate across all five pages and the new warnings address real developer footguns. Two spots need a closer look: the backend URL construction hint in upload.md points to self.router.headers.host without showing how to assemble a full URL, which could leave developers with a bare hostname; and the _replace(_js_expr=...) pattern in drag-and-drop.md relies on private Var internals without any stability caveat, which could silently break after an upgrade. docs/library/forms/upload.md (backend URL hint) and docs/enterprise/drag-and-drop.md (internal API usage) Important Files Changed
Reviews (1): Last reviewed commit: "docs: corrections and pitfalls from AI b..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| - **Type**: Returns `str` | ||
| - **Type**: Returns a frontend `Var` (a JavaScript expression), not a Python `str` | ||
|
|
||
| Because it returns a frontend Var, `rx.get_upload_url` is frontend-only: use it in component code and event triggers, not in backend event handlers or computed vars, where the value would not resolve to a usable string. If you genuinely need the upload URL as a plain string on the backend, construct it from `self.router.headers.host` instead. |
There was a problem hiding this comment.
The note says "construct it from self.router.headers.host", but self.router.headers.host only gives the Host header value (e.g., localhost:8000 or example.com). To get a usable URL string a developer would also need the protocol (http/https) and the /_upload/<filename> path. As written, a reader who follows the hint literally might write url = self.router.headers.host and end up with a bare hostname rather than a complete URL. Consider expanding the example or at least noting that the host value must be assembled with a scheme and path prefix.
| ```md alert warning | ||
| # Assign collected params to a variable first | ||
|
|
||
| Do not read fields directly off the class (e.g. `rxe.dnd.DropTarget.is_over`). Assign `collected_params` to a variable, then access fields through it: `params = rxe.dnd.DropTarget.collected_params`, then `params.is_over`. | ||
| ``` | ||
|
|
||
| When a single `@rx.memo` component renders more than one draggable or drop target, give each its own collected params name to avoid JavaScript name collisions. Use `_replace(_js_expr=...)` to create a uniquely named params Var and pass it via `_collected_params`: | ||
|
|
||
| ```python | ||
| @rx.memo | ||
| def dual_drop_zones() -> rx.Component: | ||
| left_params = rxe.dnd.DropTarget.collected_params._replace(_js_expr="leftZoneParams") | ||
| right_params = rxe.dnd.DropTarget.collected_params._replace(_js_expr="rightZoneParams") | ||
| return rx.hstack( | ||
| rxe.dnd.drop_target( | ||
| rx.box("Left", bg=rx.cond(left_params.is_over, "green.100", "gray.100")), | ||
| accept=["MyDraggable"], | ||
| _collected_params=left_params, | ||
| ), |
There was a problem hiding this comment.
_replace(_js_expr=...) relies on Var._replace and the private _js_expr attribute, both of which are internal Reflex APIs with no stability guarantees. Documenting them without a note like "this uses an internal API and may change" could leave users with broken code after an upgrade with no clear error message pointing back to this pattern. Consider adding a brief caveat so readers know they are opting into something that could require updating when Reflex's Var internals evolve.
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
| - `item`: Data object passed to drop handlers | ||
| - `on_end`: Called when drag operation ends |
There was a problem hiding this comment.
on_drag_start
The note says "use on_end to react to the completion of a drag operation", but that only covers the end-of-drag scenario. A developer explicitly looking for a way to react to the start of a drag will read this and still have no solution — on_end fires on completion, not on pickup. If there is no way to detect drag start at all, it would be clearer to say that explicitly rather than redirecting to an event that handles a different moment in the lifecycle.
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
1 participant
What
Five doc pages get corrections and pitfall callouts sourced from Reflex Build's curated knowledge base — rules our AI builder learned from real failures that turned out to be gaps (and in one case an error) in these pages. We're consolidating that knowledge base into the official docs so users and agents read the same source of truth (flexgen ENG-10044).
library/forms/upload.md— bug fix:rx.get_upload_urlwas documented as returningstr; it returns a frontendVarand is unusable in backend handlers/computed vars (backend alternative noted). Plus: uploadidmust be a string literal,file.namenote, handlers must not bebackground=True, the upload trigger button must live outside the dropzone, a short "Uploading from a Form" subsection (on_submitnever carries file data), and don't hardcode/_upload/paths.enterprise/drag-and-drop.md—@rx.memoparams are Vars (index /rx.foreach, no Python loops);on_drag_startdoesn't exist; nested drop targets fire once per layer (dedupe) + root-level drop pattern; assigncollected_paramsto a variable before reading fields, with a_collected_params=..._replace(_js_expr=...)example for multiple zones in one memo component; warning against adding a second DnD provider.state_structure/shared_state.md— sanitize tokens derived from query params (underscore restriction);_link_topitfalls (must await, use the returned instance, only exists onrx.SharedState); computed vars depending only on shared vars belong on the shared state.utility_methods/lifespan_tasks.md— a "Lifespan Tasks vs Background Events" decision section.library/typography/markdown.md— literal$pairs are parsed as LaTeX math (prices vanish, notably in streamed LLM output); escape beforerx.markdown.All additions follow each page's existing conventions (
md alertcallouts, demo blocks, doc voice). No behavioral claims were included that we couldn't verify against current reflex (e.g. we dropped a stale note aboutfile.filename— it exists as an alias of.name).🤖 Generated with Claude Code