@webflow/react - npm Package Compare versions

Comparing version 1.2.0 to 1.2.1

CHANGELOG.md

 # @webflow/react
 
+## 1.2.1
+
+### Patch Changes
+
+- Updated dependencies [dbf223b]
+  - @webflow/data-types@1.2.1
+
 ## 1.2.0
@@ -4,0 +11,0 @@

package.json

 {
   "name": "@webflow/react",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "license": "MIT",
@@ -22,9 +22,10 @@ "main": "./dist/index.cjs",
   "scripts": {
-    "build": "rm -fr ./dist; tsup",
+    "build": "tsup",
     "lint": "eslint .",
     "test": "jest --selectProjects client server --ci",
+    "test:unit": "jest --selectProjects client server --ci",
     "test:local": "jest --selectProjects client server"
   },
   "dependencies": {
-    "@webflow/data-types": "1.2.0"
+    "@webflow/data-types": "1.2.1"
   },
@@ -31,0 +32,0 @@ "peerDependencies": {

README.md

@@ -1,3 +0,240 @@
-# `@webflow/react` package
+# @webflow/react
 
-Exports Webflow React renderer interface.
+The core React integration package for building Webflow code components. This package provides the essential tools for declaring components, rendering them on both client and server, and accessing Webflow-specific context.
+
+## Installation
+
+```bash
+npm i @webflow/react
+```
+
+### Peer Dependencies
+
+This package requires the following peer dependencies:
+
+```bash
+npm i react react-dom
+```
+
+## Usage
+
+### Declaring Components
+
+Use `declareComponent` to create a Webflow code component definition. This should be the default export from your `*.webflow.tsx` file.
+
+#### Basic Example
+
+```tsx
+import { declareComponent } from "@webflow/react";
+import { props } from "@webflow/data-types";
+
+function Button({ text, link }) {
+  return (
+    <a href={link?.href} target={link?.target}>
+      {text}
+    </a>
+  );
+}
+
+export default declareComponent(Button, {
+  name: "Button",
+  description: "A customizable button component",
+  props: {
+    text: props.Text({ name: "Text", defaultValue: "Click me" }),
+    link: props.Link({ name: "Link" }),
+  },
+});
+```
+
+#### With Decorators
+
+Decorators allow you to wrap your component with additional functionality, such as CSS-in-JS providers:
+
+```tsx
+import { declareComponent } from "@webflow/react";
+import { emotionShadowDomDecorator } from "@webflow/emotion-utils";
+
+export default declareComponent(MyComponent, {
+  name: "My Component",
+  decorators: [emotionShadowDomDecorator],
+});
+```
+
+#### With Options
+
+```tsx
+export default declareComponent(MyComponent, {
+  name: "My Component",
+  props: {
+    // ... your props
+  },
+  options: {
+    applyTagSelectors: true, // Provide styles targeting tag selectors (default: false)
+    ssr: true, // Enable server-side rendering (default: true)
+  },
+});
+```
+
+### Using Webflow Context
+
+Access Webflow-specific context data in your components using the `useWebflowContext` hook:
+
+```tsx
+import { useWebflowContext } from "@webflow/react";
+
+function MyComponent() {
+  const { mode, interactive, locale } = useWebflowContext();
+
+  return (
+    <div>
+      <p>Mode: {mode}</p>
+      <p>Interactive: {interactive ? "Yes" : "No"}</p>
+      <p>Locale: {locale}</p>
+    </div>
+  );
+}
+```
+
+**Context Properties:**
+
+- `mode` - The current mode (`"design"` or `"preview"`)
+- `interactive` - Whether the component is in an interactive state
+- `locale` - The current locale (e.g., `"en-US"`)
+
+## Server-Side Rendering
+
+This package provides a server-side renderer for React components. The `ServerRenderer` provides:
+
+- Server-side rendering with `renderToString` and `renderToStream`
+- Support for creating slot elements with `createSlot`
+- Automatic handling of Webflow context during SSR
+
+**Note:** For CSS-in-JS libraries like Emotion or styled-components, use their respective server renderers instead:
+
+- `@webflow/emotion-utils/server`
+- `@webflow/styled-components-utils/server`
+
+Configure the server renderer in your `webflow.json` file:
+
+```json
+{
+  "library": {
+    "renderer": {
+      "server": "@webflow/emotion-utils/server"
+    }
+  }
+}
+```
+
+## API Reference
+
+### `declareComponent`
+
+Creates a Webflow code component definition.
+
+**Type:**
+
+```typescript
+<P extends {}>(
+  Component: React.ComponentType<P>,
+  data: ComponentData<P, React.ReactNode, React.ComponentType<P>>,
+) => ComponentDefinition<React.ComponentType<P>, React.ReactNode, P>;
+```
+
+**Parameters:**
+
+- `Component` - The React component to render
+- `data` - Component metadata and configuration
+  - `data.name` - The display name of the component
+  - `data.description` (optional) - Description of the component
+  - `data.group` (optional) - Group for organizing components
+  - `data.props` (optional) - Component props configuration
+  - `data.options` (optional) - Additional options
+    - `data.options.applyTagSelectors` (optional) - Provide tag selector styles (default: `false`)
+    - `data.options.ssr` (optional) - Enable server-side rendering (default: `true`)
+  - `data.decorators` (optional) - Array of decorator functions
+
+**Returns:** A Webflow code component definition
+
+### `useWebflowContext`
+
+Hook to access Webflow context data.
+
+**Type:**
+
+```typescript
+() => WebflowContextType;
+```
+
+**Returns:**
+
+```typescript
+{
+  mode: "design" | "preview";
+  interactive: boolean;
+  locale: string;
+}
+```
+
+### `ClientRenderer`
+
+A factory that creates a client-side renderer for a React component.
+
+**Type:**
+
+```typescript
+ComponentClientRendererFactory<
+  React.ComponentType<ComponentRuntimeProps<React.ReactNode>>,
+  ReactDOM.Root,
+  React.ReactNode
+>;
+```
+
+**Methods:**
+
+- `mount(domNode)` - Creates a React root on the provided DOM node
+- `hydrate(domNode, props?, options?)` - Hydrates a server-rendered component
+- `render(root, props?, options?)` - Renders the component to an existing root
+- `createSlot(name)` - Creates a named slot element for component composition
+
+### `ServerRenderer`
+
+A factory that creates a server-side renderer for a React component.
+
+**Type:**
+
+```typescript
+ComponentServerRendererFactory<
+  React.ComponentType<ComponentRuntimeProps<React.ReactNode>>,
+  PipeableStream,
+  ReactDOMServer.RenderToPipeableStreamOptions,
+  React.ReactNode,
+  ReactDOMServer.ServerOptions
+>;
+```
+
+**Methods:**
+
+- `renderToStream(props?, options?, streamOptions?)` - Renders component to a pipeable stream
+- `renderToString(props?, options?, stringOptions?)` - Renders component to a string
+- `createElement(props?, options?)` - Creates a React element with the component
+- `createSlot(name)` - Creates a named slot element for component composition
+
+### `applyDecorators`
+
+Utility function to apply an array of decorators to a component.
+
+**Type:**
+
+```typescript
+<P extends {}>(
+  Component: React.ComponentType<P>,
+  decorators: Array<
+    (Component: React.ComponentType<P>) => React.ComponentType<P>
+  >,
+) => React.ComponentType<P>;
+```
+
+## License
+
+MIT

No alert changes

Improved metrics

Total package byte prevSize

19315

44.16%

Number of lines in readme file

241

5925%

Dependency changes

• + Added

  @webflow/data-types@1.2.1
  (transitive)

• - Removed

  @webflow/data-types@1.2.0
  (transitive)

• Updated

  @webflow/data-types@1.2.1