repository·main·Indexed 23 days ago
https://github.com/redwoodjs/sdkA server-first React framework leveraging Vite to enable React Server Components and Server Functions with a type-safe, standards-compliant routing system. The SDK includes the rwsdk-community package for extensions and utilities, and supports integration with UI libraries like Chakra UI v3 and Base UI. It is designed for Cloudflare Worker environments and utilizes a Test-Bridge pattern for integration testing via vitest-pool-workers.
This playground demonstrates a pattern for using Drizzle ORM to perform type-safe database queries against Cloudflare Durable Objects.
Key architectural components include:
The rwsdk-community package provides common extensions, utilities, and community-contributed features for the RedwoodSDK.
Warning on Stability: This package follows a separate stability policy from the core RedwoodSDK. Features within rwsdk-community may undergo breaking changes at any time without a major version bump. It is recommended to use these features with caution in critical production environments.
RedwoodSDK is a React framework designed for Cloudflare. It functions as a Vite plugin that enables modern web capabilities including:
Local development uses Miniflare to emulate the Cloudflare runtime, providing out-of-the-box access to Durable Objects, D1 (database), R2 (blob storage), and Queues without additional installation.
The Typed Routes Playground is a demonstration environment for testing linkFor functionality. It showcases how routes are automatically inferred from the application definition to provide type-safe link generation.
Key features demonstrated include:
//users/:id/files/*npm run devThe Base UI Showcase playground is built using the following stack:
@base-ui-components/react)The RSC Kitchen Sink Playground demonstrates how to combine server and client components and implement various interaction patterns using React Server Components:
onClick server actions: Triggering server-side logic from client-side event handlers.Response.redirect(). The RedwoodSDK converts this into an intermediate format on the server, which is then handled on the client to perform the actual navigation.The community/playground/ directory contains examples maintained by the community rather than the official RedwoodSDK team.
Important considerations when using these examples:
playground/ surface area.Passkey authentication in the RedwoodSDK is a passwordless method built on the WebAuthn standard. It utilizes public-key cryptography to allow users to sign in using biometric data (such as fingerprints or face scans) or device PINs.
The SDK's Passkey addon simplifies this implementation by bundling:
Modules marked with "use server" are transformed to create a secure RPC (Remote Procedure Call) boundary between the client and the server.
client and ssr EnvironmentsTo prevent leaking server-side implementation to the browser, the entire module implementation is stripped and replaced with an RPC stub created by createServerReference.
worker EnvironmentIn the worker environment, the "use server" directive is removed so the code can execute. Additionally, registerServerReference is called for each export to attach metadata, allowing the framework's RPC layer to route incoming client calls to the correct function.
| Environment | "use client" Behavior | "use server" Behavior |
|---|---|---|
worker | Uses registerClientReference to provide both placeholders (for RSC) and real objects (for SSR/Server logic). | Removes directive and calls registerServerReference to enable RPC routing. |
client / ssr | Removes directive; uses full implementation. | Strips implementation; replaces with createServerReference RPC stubs. |
// Example of a transformed "use server" module in the `client` environment
import { createServerReference } from "rwsdk/client";
export let sendMessage = createServerReference("/src/actions/sendMessage.ts", "sendMessage");
// Example of a transformed "use server" module in the `worker` environment
import { registerServerReference } from "rwsdk/worker";
export async function sendMessage(message: string) {
// ... database logic
return { success: true };
}
registerServerReference(sendMessage, "/src/actions/sendMessage.ts", "sendMessage");Because parsing code into an Abstract Syntax Tree (AST) is computationally expensive, the transformJsxScriptTagsPlugin.mts uses an "early exit" strategy to minimize performance impact during development and builds.
Before performing full AST parsing, the plugin performs a lightweight string search on the raw source code for specific keywords indicating the presence of JSX elements, such as:
jsx("script"jsxs("link"If these keywords are not found, the plugin skips the expensive transformation steps for that file entirely, ensuring negligible overhead for the majority of files in a project.
In rwsdk, you can interact with server-side functions using two distinct patterns depending on whether you need data or a UI update:
serverQuery: Used when you only need the returned data. It uses the x-rsc-data-only: true header to tell the server to skip rendering the full React component tree. This preserves existing client-side page state and avoids the overhead of transporting the entire UI tree. It does not cause the page to hydrate or re-render.serverAction: Used for mutations. The server returns the full updated UI tree, and the client runtime will refresh the UI with this new tree. This allows data mutations to be reflected in the UI immediately through hydration and re-rendering.