diff --git a/docs/api-reference/next/streaming.md b/docs/api-reference/next/streaming.md
index 926a3a09c61ef..32142ee7e9ead 100644
--- a/docs/api-reference/next/streaming.md
+++ b/docs/api-reference/next/streaming.md
@@ -1,11 +1,95 @@
---
-description: Use streaming related APIs to build streaming SSR Next.js pages.
+description: Streaming related APIs to build Next.js apps in streaming SSR or with React Server Components.
---
# next/streaming
+The `next/streaming` module provides streaming related APIs to port the existing functionality of Next.js app to streaming scenarios or assign users ability to interact much easier with React Server Components.
+
## unstable_useWebVitalsReport
-Next.js provides an App component level function `reportWebVitals` for tracking performance metrics, checkout [measuring-performance](docs/advanced-features/measuring-performance) for more details. With moving to streaming SSR, you might not be able to
+Next.js provides an App component level function `reportWebVitals` for tracking performance metrics, checkout [measuring-performance](docs/advanced-features/measuring-performance) for more details. With moving to server components, you might have a pure server side custom `_app` component which doesn't run client effects.
+
+With this API, you're able to track web vitals metrics through this hook in client components.
+
+```jsx
+// pages/_app.js
+import { unstable_useWebVitalsReport } from 'next/streaming'
+
+export default function Home() {
+ unstable_useWebVitalsReport((data) => {
+ console.log(data)
+ })
+
+ return
Home Page
+}
+```
+
+Or it could also be an alternative way for you to replace static exported `reportWebVitals` function in your existing \_app.
+
+```jsx
+// pages/_app.server.js
+import Layout from '../components/layout.client.js'
+
+export default function App({ children }) {
+ return {children}
+}
+```
+
+```jsx
+// components/layout.client.js
+import { unstable_useWebVitalsReport as useWebVitalsReport } from 'next/streaming'
+
+export default function Layout() {
+ useWebVitalsReport((data) => {
+ console.log(data)
+ })
+
+ return (
+
+ )
+}
+```
## unstable_useRefreshRoot
+
+Since server components are rendered on server side when requesting to server, in some case you might need to partially refresh server rendered content.
+
+For instance, you build a search bar in client component and display few search results by server components, you'd like to update the search results while typing. Then you'd like to re-render the results list in a certain frequency, it could be each typing, or be batched by debounce.
+
+The hook `unstable_useRefreshRoot` returns a `refresh` API to let you rerender the React tree smoothly without flicking. This is only allowed to be used on client side and will only effect server components so far.
+
+```jsx
+// pages/index.server.js
+import Search from '../components/search.client.js'
+import SearchResults from '../components/search-results.server.js'
+
+function Home() {
+ return (
+
+
+
+
+ )
+}
+```
+
+```jsx
+// components/search.client.js
+import { unstable_useRefreshRoot as useRefreshRoot } from 'next/streaming'
+
+export default function Search() {
+ const refresh = useRefreshRoot()
+
+ return (
+ {
+ refresh()
+ }}
+ />
+ )
+}
+```
diff --git a/docs/manifest.json b/docs/manifest.json
index 4f67241d723c3..c635c73c565d8 100644
--- a/docs/manifest.json
+++ b/docs/manifest.json
@@ -365,6 +365,10 @@
"title": "next/server",
"path": "/docs/api-reference/next/server.md"
},
+ {
+ "title": "next/streaming",
+ "path": "/docs/api-reference/next/streaming.md"
+ },
{
"title": "Edge Runtime",
"path": "/docs/api-reference/edge-runtime.md"