Using Weavy with React
In addition to the Weavy UIKit, which is based on web components, we also offer a UIKit for React to provide an idiomatic experience for React users. Under the hood, it is powered by the Weavy UIKit for automatic access to all the latest features and updates.
Prerequisites
- A Weavy environment.
- A token endpoint in your backend that can provide an
access_token
for your authenticated user. - React v16 or later.
Configure your React project
First, you need a React project to place Weavy in. If you already have a React project this step can be skipped. Otherwise we recommend following the official React installation guide as there are several great frameworks and setups to choose from when setting up a React project. Weavy supports regular React projects as well as server rendered projects (SSR), such as Next.js using React Server Components.
Install Weavy UIKit for React
Run the following command to install the Weavy UIKit for React in your project:
npm install @weavy/uikit-react
Please refer to uikit-react migration guide if you are upgrading from a previous version of Weavy UIKit for React.
Initialize the UIKit
Next you need to initialize the UIKit with some basic configuration settings. At the very least, you need to set the url
to your Weavy environment and a tokenUrl
or tokenFactory
for authentication.
Refer to the UIKit reference documentation for a full list of options.
Weavy can be configured using the <WyContext />
component. Provide any options as attributes on the component. The <WyContext />
creates a Weavy instance and provides it to the components.
You may alternatively import the useWeavy
hook from the @weavy/uikit-react
package and pass your configuration to the hook as options. After the useWeavy
hook has initialized, it returns the Weavy instance.
Hooks are not available server side when using Server Side Rendering (SSR) with React Server Components. To configure Weavy in server components, it's recommended to use the <WyContext />
component instead of the useWeavy()
hook. Configuration for the tokenFactory
can with advantage be provided using a server action which runs directly on the server.
The <WyContext />
component may alternatively be used with configuration properties in JSX instead of using the useWeavy
hook.
We recommend placing the configuration in a component at the highest level possible in the render-tree. Having the configuration in multiple places may cause unexpected conflicting behavior.
// weavy-component.jsx
'use client'
import React from "react";
import { WyContext } from "@weavy/uikit-react";
import { tokenFactory } from "./server-actions"
export default function WeavyComponent() {
return (
<>
<WyContext
url="{WEAVY-URL}"
tokenFactory={tokenFactory}
>
...
<SomeComponent />
</WyContext>
</>
);
}
// server-actions.ts
'use server'
export async function tokenFactory(refresh) {
return "wyu_**********";
}
Note: You need to use the App Router available in Next.js v13+ to make use of React Server Components.
import React from "react";
import { useWeavy } from "@weavy/uikit-react";
import { SomeComponent } from "./SomeComponent";
export function App() {
const weavy = useWeavy({
url: "{WEAVY-URL}",
tokenUrl: "https://example.com/myapp/token",
});
return (
<>
...
<SomeComponent />
</>
);
}
Pitfall: Avoid using
new URL(...)
in your options as React then creates a new URL on each render, causing Weavy to be reconfigured on each render.
Weavy components
All web components in the Weavy UIKit are available as React components but with tag names adapted to the React framework,
for example <WyChat>
instead of <wy-chat></wy-chat>
. Property binding for attributes using prop={value}
syntax may be used normally just as expected.
import React from "react";
import { WyChat } from "@weavy/uikit-react";
export function SomeComponent() {
const chatUid = "test-chat";
return <WyChat uid={chatUid} />;
}
React component | Web component |
---|---|
<WyChat /> |
<wy-chat></wy-chat> |
<WyComments /> |
<wy-comments></wy-comments> |
<WyContext /> |
<wy-context><wy-context> |
<WyFiles /> |
<wy-files></wy-files> |
<WyMessenger /> |
<wy-messenger></wy-messenger> |
<WyNotifications /> |
<wy-notifications></wy-notifications> |
<WyPosts /> |
<wy-posts></wy-posts> |
Accessing Weavy in components
The created Weavy instance can be accessed from components using a context consumer.
When using the <WyContext>
syntax for configuration, Weavy can be accessed with the React context API by importing WeavyContext
and use the standard useContext(WeavyContext) hook as long as the component is a child of the <WyContext>
.
If the Weavy instance was created using the useWeavy()
hook, you may alternatively create your own React context provider or use the useWeavyContext(ref)
hook to access it using the Context Community Protocol.
The useWeavyContext(ref)
must be used with an element reference from any child from the DOM tree since it relies on standard events in the DOM.
import React, { useContext } from "react"
import { WeavyContext } from "@weavy/uikit-react"
export const MyComponent = () => {
// Requires that weavy is configured using <WyContext>
const weavy = useContext(WeavyContext)
useEffect(() => {
if (weavy) {
console.log("We got weavy", weavy.version)
}
}, [weavy])
...
return (
<></>
)
}
import React, { useRef } from "react"
import { useWeavyContext } from "@weavy/uikit-react"
export const MyComponent = () => {
const domRef = useRef(null)
const weavy = useWeavyContext(domRef)
useEffect(() => {
if (weavy) {
console.log("We got weavy", weavy.version)
}
}, [weavy])
...
return (
<>
<span ref={domRef}></span>
...
</>
)
}
Tutorials and more
For additional info and tutorials on using Weavy with React you should also visit our technology page on React.