Unverified Commit 766b7cbf authored by Josh Story's avatar Josh Story Committed by GitHub

Stabilize `unstable_io` (#93621)

Removes the unstable prefix from `unstable_io`. Since this was only
shipped in canaries with the unstable prefix we are going to just remove
it without retaining the unstable prefix simultaneously.
parent 30099378
---
title: unstable_io
description: API Reference for the unstable_io function.
title: io
description: API Reference for the io function.
version: draft
---
`unstable_io()` informs Next.js that an IO operation will follow this call. When [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents) is not enabled or when rendering in Pages Router, signifying IO in this way is not meaningful and the call will always resolve immediately. When Cache Components is enabled, you may be required to add `await unstable_io()` preceding synchronous IO that is encountered while prerendering pages (`new Date()` for example). Additionally, if you want to avoid having genuine uncached IO invoked while prerendering, you shield it by preceeding it with `await unstable_io()`.
`io()` informs Next.js that an IO operation will follow this call. When [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents) is not enabled or when rendering in Pages Router, signifying IO in this way is not meaningful and the call will always resolve immediately. When Cache Components is enabled, you may be required to add `await io()` preceding synchronous IO that is encountered while prerendering pages (`new Date()` for example). Additionally, if you want to avoid having genuine uncached IO invoked while prerendering, you shield it by preceeding it with `await io()`.
```ts filename="app/page.tsx" switcher
import { unstable_io } from 'next/cache'
import { io } from 'next/cache'
import { db } from '@/lib/db'
export default async function Page() {
// Synchronous IO: new Date() would fail during prerender without this
await unstable_io()
await io()
const now = new Date().toISOString()
// Async IO: the query would run and be discarded during prerender;
// unstable_io() above lets Next.js skip it entirely
// io() above lets Next.js skip it entirely
const orders = await db.query('SELECT * FROM orders LIMIT 10')
return (
......@@ -33,16 +33,16 @@ export default async function Page() {
```
```js filename="app/page.js" switcher
import { unstable_io } from 'next/cache'
import { io } from 'next/cache'
import { db } from '@/lib/db'
export default async function Page() {
// Synchronous IO: new Date() would fail during prerender without this
await unstable_io()
await io()
const now = new Date().toISOString()
// Async IO: the query would run and be discarded during prerender;
// unstable_io() above lets Next.js skip it entirely
// io() above lets Next.js skip it entirely
const orders = await db.query('SELECT * FROM orders LIMIT 10')
return (
......@@ -62,16 +62,16 @@ export default async function Page() {
[`connection()`](/docs/app/api-reference/functions/connection) requires an active HTTP request context and signals that the component needs request-specific data. It is imported from `next/server`.
`unstable_io()` does not require a request context. It can be used inside `"use cache"` scopes, client components, and anywhere you perform IO that should not be included in a static prerender. It is imported from `next/cache`.
`io()` does not require a request context. It can be used inside `"use cache"` scopes, client components, and anywhere you perform IO that should not be included in a static prerender. It is imported from `next/cache`.
Use `connection()` when you need the request itself (cookies, headers, etc.). Use `unstable_io()` when you perform IO that is independent of the request but should still prevent static prerendering.
Use `connection()` when you need the request itself (cookies, headers, etc.). Use `io()` when you perform IO that is independent of the request but should still prevent static prerendering.
## Reference
### Type
```ts
function unstable_io(): Promise<void>
function io(): Promise<void>
```
### Parameters
......@@ -84,12 +84,12 @@ function unstable_io(): Promise<void>
## Good to know
- `unstable_io()` is imported from `next/cache`, not `next/server`.
- Inside `"use cache"` scopes, `unstable_io()` resolves immediately. The cache captures the IO result at fill time.
- In client components, `unstable_io()` resolves immediately since there is no prerender context in the browser.
- `io()` is imported from `next/cache`, not `next/server`.
- Inside `"use cache"` scopes, `io()` resolves immediately. The cache captures the IO result at fill time.
- In client components, `io()` resolves immediately since there is no prerender context in the browser.
### Version History
| Version | Changes |
| --------- | -------------------- |
| `v16.x.x` | `unstable_io` added. |
| Version | Changes |
| --------- | ----------- |
| `v16.x.x` | `io` added. |
......@@ -9,7 +9,7 @@ export {
export { unstable_noStore } from 'next/dist/server/web/spec-extension/unstable-no-store'
export { unstable_io } from 'next/dist/server/request/io'
export { io } from 'next/dist/server/request/io'
import { cacheTag } from 'next/dist/server/use-cache/cache-tag'
......
......@@ -17,7 +17,7 @@ if (process.env.NEXT_RUNTIME === '') {
}
},
unstable_noStore: function unstable_noStore() {},
unstable_io: require('next/dist/client/request/io.browser').unstable_io,
io: require('next/dist/client/request/io.browser').io,
updateTag: notAvailableInClient('updateTag'),
revalidateTag: notAvailableInClient('revalidateTag'),
......@@ -46,7 +46,7 @@ if (process.env.NEXT_RUNTIME === '') {
unstable_noStore:
require('next/dist/server/web/spec-extension/unstable-no-store')
.unstable_noStore,
unstable_io: require('next/dist/server/request/io').unstable_io,
io: require('next/dist/server/request/io').io,
cacheLife: require('next/dist/server/use-cache/cache-life').cacheLife,
cacheTag: require('next/dist/server/use-cache/cache-tag').cacheTag,
}
......@@ -94,4 +94,4 @@ exports.unstable_cacheLife = cacheExports.unstable_cacheLife
exports.cacheTag = cacheExports.cacheTag
exports.unstable_cacheTag = cacheExports.unstable_cacheTag
exports.refresh = cacheExports.refresh
exports.unstable_io = cacheExports.unstable_io
exports.io = cacheExports.io
......@@ -5,9 +5,9 @@ const resolvedIOPromise: Promise<void> = Promise.resolve(undefined)
;(resolvedIOPromise as any).value = undefined
/**
* Browser implementation of unstable_io(). On the client there is no
* Browser implementation of io(). On the client there is no
* prerender context so we always resolve immediately.
*/
export function unstable_io(): Promise<void> {
export function io(): Promise<void> {
return resolvedIOPromise
}
......@@ -29,7 +29,7 @@ describe('cache-life-type-utils', () => {
refresh,
} from 'next/dist/server/web/spec-extension/revalidate'
export { unstable_noStore } from 'next/dist/server/web/spec-extension/unstable-no-store'
export { unstable_io } from 'next/dist/server/request/io'
export { io } from 'next/dist/server/request/io'
/**
......@@ -187,7 +187,7 @@ describe('cache-life-type-utils', () => {
refresh,
} from 'next/dist/server/web/spec-extension/revalidate'
export { unstable_noStore } from 'next/dist/server/web/spec-extension/unstable-no-store'
export { unstable_io } from 'next/dist/server/request/io'
export { io } from 'next/dist/server/request/io'
/**
......@@ -265,7 +265,7 @@ describe('cache-life-type-utils', () => {
refresh,
} from 'next/dist/server/web/spec-extension/revalidate'
export { unstable_noStore } from 'next/dist/server/web/spec-extension/unstable-no-store'
export { unstable_io } from 'next/dist/server/request/io'
export { io } from 'next/dist/server/request/io'
/**
......@@ -342,7 +342,7 @@ describe('cache-life-type-utils', () => {
refresh,
} from 'next/dist/server/web/spec-extension/revalidate'
export { unstable_noStore } from 'next/dist/server/web/spec-extension/unstable-no-store'
export { unstable_io } from 'next/dist/server/request/io'
export { io } from 'next/dist/server/request/io'
/**
......@@ -420,7 +420,7 @@ describe('cache-life-type-utils', () => {
refresh,
} from 'next/dist/server/web/spec-extension/revalidate'
export { unstable_noStore } from 'next/dist/server/web/spec-extension/unstable-no-store'
export { unstable_io } from 'next/dist/server/request/io'
export { io } from 'next/dist/server/request/io'
/**
......@@ -502,7 +502,7 @@ describe('cache-life-type-utils', () => {
refresh,
} from 'next/dist/server/web/spec-extension/revalidate'
export { unstable_noStore } from 'next/dist/server/web/spec-extension/unstable-no-store'
export { unstable_io } from 'next/dist/server/request/io'
export { io } from 'next/dist/server/request/io'
/**
......
......@@ -177,7 +177,7 @@ declare module 'next/cache' {
refresh,
} from 'next/dist/server/web/spec-extension/revalidate'
export { unstable_noStore } from 'next/dist/server/web/spec-extension/unstable-no-store'
export { unstable_io } from 'next/dist/server/request/io'
export { io } from 'next/dist/server/request/io'
${overloads}
......
......@@ -21,10 +21,10 @@ const resolvedIOPromise: Promise<void> = Promise.resolve(undefined)
* point, creating a dynamic boundary. Inside `"use cache"` scopes or during
* a real request it resolves immediately.
*
* Unlike `connection()`, `unstable_io()` does not require an actual HTTP
* request and can be used freely inside cache scopes and client components.
* Unlike `connection()`, `io()` does not require an actual HTTP request and
* can be used freely inside cache scopes and client components.
*/
export function unstable_io(): Promise<void> {
export function io(): Promise<void> {
const workStore = workAsyncStorage.getStore()
const workUnitStore = workUnitAsyncStorage.getStore()
......@@ -59,7 +59,7 @@ export function unstable_io(): Promise<void> {
return makeHangingPromise(
workUnitStore.renderSignal,
workStore.route,
'`unstable_io()`'
'`io()`'
)
case 'prerender-ppr':
// Dead code to be removed when we eliminate legacy ppr code
......@@ -68,7 +68,7 @@ export function unstable_io(): Promise<void> {
case 'cache':
case 'private-cache':
case 'unstable-cache':
// Inside cache scopes, unstable_io() resolves immediately.
// Inside cache scopes, io() resolves immediately.
// Caches can contain IO-dependent code like new Date() — it will
// simply return the value at cache-fill time.
// ...
......@@ -79,7 +79,7 @@ export function unstable_io(): Promise<void> {
// ...
// intentional fallthrough
case 'validation-client':
// unstable_io() is usable in client components, resolve immediately.
// io() is usable in client components, resolve immediately.
// The reason we take this position is most io shielding you would do
// in a browser is for sync IO as there aren't many non-fetch based IO
// operations you can do in the browser that have meaningful latency.
......
......@@ -373,7 +373,7 @@
"test/production/app-dir/resume-data-cache/resume-data-cache.test.ts",
"test/production/app-dir/unstable-cache-foreground-revalidate/unstable-cache-foreground-revalidate.test.ts",
"test/e2e/app-dir/parallel-routes-root-param-dynamic-child/parallel-routes-root-param-dynamic-child.test.ts",
"test/e2e/app-dir/unstable-io/unstable-io.test.ts"
"test/e2e/app-dir/io/io.test.ts"
]
}
}
import { Suspense } from 'react'
import { unstable_io } from 'next/cache'
import { io } from 'next/cache'
import { getSentinelValue } from '../getSentinelValue'
export default function Page() {
return (
<>
<p>
This page uses unstable_io() inside a Suspense boundary. Without cache
components unstable_io() is a no-op during prerendering so the entire
page should be fully static.
This page uses io() inside a Suspense boundary. With cache components
the content after io() should be dynamic and rendered at request time,
not during the build prerender.
</p>
<div id="before">{getSentinelValue()}</div>
<Suspense fallback={<div id="fallback">loading...</div>}>
......@@ -20,6 +20,6 @@ export default function Page() {
}
async function DynamicComponent() {
await unstable_io()
await io()
return <div id="after-io">{getSentinelValue()}</div>
}
import { Suspense } from 'react'
import { unstable_io } from 'next/cache'
import { io } from 'next/cache'
import { getSentinelValue } from '../getSentinelValue'
export default function Page() {
return (
<>
<p>
This page uses unstable_io() inside a "use cache" function. Inside cache
scopes unstable_io() resolves immediately so the cached value should be
computed at cache-fill time during the build.
This page uses io() inside a "use cache" function. Inside cache scopes
io() resolves immediately so the cached value should be computed at
cache-fill time during the build.
</p>
<Suspense fallback="loading...">
<CachedComponent />
......@@ -25,6 +25,6 @@ async function CachedComponent() {
async function getCachedValue() {
'use cache'
await unstable_io()
await io()
return getSentinelValue()
}
import { unstable_io } from 'next/cache'
import { io } from 'next/cache'
export default function PagesGSP({ rendered }: { rendered: string }) {
return (
<>
<p>This page uses unstable_io() in getStaticProps.</p>
<p>This page uses io() in getStaticProps.</p>
<div id="pages-content">{rendered}</div>
</>
)
}
export async function getStaticProps() {
await unstable_io()
await io()
return { props: { rendered: 'ok' } }
}
import { unstable_io } from 'next/cache'
import { io } from 'next/cache'
export default function PagesGSSP({ rendered }: { rendered: string }) {
return (
<>
<p>This page uses unstable_io() in getServerSideProps.</p>
<p>This page uses io() in getServerSideProps.</p>
<div id="pages-content">{rendered}</div>
</>
)
}
export async function getServerSideProps() {
await unstable_io()
await io()
return { props: { rendered: 'ok' } }
}
import React from 'react'
import { unstable_io } from 'next/cache'
import { io } from 'next/cache'
export default function PagesUse() {
if (typeof React.use === 'function') {
React.use(unstable_io())
React.use(io())
}
return (
<>
<p>This page calls React.use(unstable_io()) in the component body.</p>
<p>This page calls React.use(io()) in the component body.</p>
<div id="pages-content">ok</div>
</>
)
......
import { Suspense } from 'react'
import { unstable_io } from 'next/cache'
import { io } from 'next/cache'
import { getSentinelValue } from '../getSentinelValue'
export default function Page() {
return (
<>
<p>
This page uses unstable_io() inside a Suspense boundary. With cache
components the content after unstable_io() should be dynamic and
rendered at request time, not during the build prerender.
This page uses io() inside a Suspense boundary. Without cache components
io() is a no-op during prerendering so the entire page should be fully
static.
</p>
<div id="before">{getSentinelValue()}</div>
<Suspense fallback={<div id="fallback">loading...</div>}>
......@@ -20,6 +20,6 @@ export default function Page() {
}
async function DynamicComponent() {
await unstable_io()
await io()
return <div id="after-io">{getSentinelValue()}</div>
}
import { unstable_io } from 'next/cache'
import { io } from 'next/cache'
export default function PagesGSP({ rendered }: { rendered: string }) {
return (
<>
<p>This page uses unstable_io() in getStaticProps.</p>
<p>This page uses io() in getStaticProps.</p>
<div id="pages-content">{rendered}</div>
</>
)
}
export async function getStaticProps() {
await unstable_io()
await io()
return { props: { rendered: 'ok' } }
}
import { unstable_io } from 'next/cache'
import { io } from 'next/cache'
export default function PagesGSSP({ rendered }: { rendered: string }) {
return (
<>
<p>This page uses unstable_io() in getServerSideProps.</p>
<p>This page uses io() in getServerSideProps.</p>
<div id="pages-content">{rendered}</div>
</>
)
}
export async function getServerSideProps() {
await unstable_io()
await io()
return { props: { rendered: 'ok' } }
}
import React from 'react'
import { unstable_io } from 'next/cache'
import { io } from 'next/cache'
export default function PagesUse() {
if (typeof React.use === 'function') {
React.use(unstable_io())
React.use(io())
}
return (
<>
<p>This page calls React.use(unstable_io()) in the component body.</p>
<p>This page calls React.use(io()) in the component body.</p>
<div id="pages-content">ok</div>
</>
)
......
import { nextTestSetup } from 'e2e-utils'
describe('unstable_io with cache components', () => {
describe('io with cache components', () => {
const { next, isNextDev, skipped } = nextTestSetup({
files: __dirname + '/fixtures/cache-components',
skipDeployment: true,
......@@ -10,7 +10,7 @@ describe('unstable_io with cache components', () => {
return
}
it('should make content after unstable_io() dynamic during prerender', async () => {
it('should make content after io() dynamic during prerender', async () => {
const $ = await next.render$('/io-boundary')
if (isNextDev) {
// In dev mode everything renders at runtime
......@@ -18,9 +18,9 @@ describe('unstable_io with cache components', () => {
expect($('#after-io').text()).toBe('at runtime')
expect($('#page').text()).toBe('at runtime')
} else {
// In production with cache components, unstable_io() creates a dynamic
// In production with cache components, io() creates a dynamic
// boundary. Content in the static shell is rendered at buildtime.
// Content after unstable_io() is rendered at request time because the
// Content after io() is rendered at request time because the
// hanging promise prevented it from executing during the build prerender.
expect($('#before').text()).toBe('at buildtime')
expect($('#page').text()).toBe('at buildtime')
......@@ -34,7 +34,7 @@ describe('unstable_io with cache components', () => {
expect($('#cached-value').text()).toBe('at runtime')
expect($('#page').text()).toBe('at runtime')
} else {
// unstable_io() inside "use cache" is a no-op so the cached value is
// io() inside "use cache" is a no-op so the cached value is
// computed at cache-fill time during the build
expect($('#cached-value').text()).toBe('at buildtime')
expect($('#page').text()).toBe('at buildtime')
......@@ -57,7 +57,7 @@ describe('unstable_io with cache components', () => {
})
})
describe('unstable_io without cache components', () => {
describe('io without cache components', () => {
const { next, isNextDev, skipped } = nextTestSetup({
files: __dirname + '/fixtures/default',
skipDeployment: true,
......@@ -74,7 +74,7 @@ describe('unstable_io without cache components', () => {
expect($('#after-io').text()).toBe('at runtime')
expect($('#page').text()).toBe('at runtime')
} else {
// Without cache components, unstable_io() resolves immediately during
// Without cache components, io() resolves immediately during
// prerendering so the entire page is fully static
expect($('#before').text()).toBe('at buildtime')
expect($('#after-io').text()).toBe('at buildtime')
......
......@@ -8159,17 +8159,17 @@
"flakey": [],
"runtimeError": false
},
"test/e2e/app-dir/unstable-io/unstable-io.test.ts": {
"passed": [
"unstable_io with cache components should make content after unstable_io() dynamic during prerender",
"unstable_io with cache components should resolve immediately inside a \"use cache\" scope",
"unstable_io with cache components should work in pages router with React.use() (CC)",
"unstable_io with cache components should work in pages router with getServerSideProps (CC)",
"unstable_io with cache components should work in pages router with getStaticProps (CC)",
"unstable_io without cache components should be a no-op during prerender without cache components",
"unstable_io without cache components should work in pages router with React.use()",
"unstable_io without cache components should work in pages router with getServerSideProps",
"unstable_io without cache components should work in pages router with getStaticProps"
"test/e2e/app-dir/io/io.test.ts": {
"passed": [
"io with cache components should make content after io() dynamic during prerender",
"io with cache components should resolve immediately inside a \"use cache\" scope",
"io with cache components should work in pages router with React.use() (CC)",
"io with cache components should work in pages router with getServerSideProps (CC)",
"io with cache components should work in pages router with getStaticProps (CC)",
"io without cache components should be a no-op during prerender without cache components",
"io without cache components should work in pages router with React.use()",
"io without cache components should work in pages router with getServerSideProps",
"io without cache components should work in pages router with getStaticProps"
],
"failed": [],
"pending": [],
......@@ -10533,17 +10533,17 @@
"flakey": [],
"runtimeError": false
},
"test/e2e/app-dir/unstable-io/unstable-io.test.ts": {
"passed": [
"unstable_io with cache components should make content after unstable_io() dynamic during prerender",
"unstable_io with cache components should resolve immediately inside a \"use cache\" scope",
"unstable_io with cache components should work in pages router with React.use() (CC)",
"unstable_io with cache components should work in pages router with getServerSideProps (CC)",
"unstable_io with cache components should work in pages router with getStaticProps (CC)",
"unstable_io without cache components should be a no-op during prerender without cache components",
"unstable_io without cache components should work in pages router with React.use()",
"unstable_io without cache components should work in pages router with getServerSideProps",
"unstable_io without cache components should work in pages router with getStaticProps"
"test/e2e/app-dir/io/io.test.ts": {
"passed": [
"io with cache components should make content after io() dynamic during prerender",
"io with cache components should resolve immediately inside a \"use cache\" scope",
"io with cache components should work in pages router with React.use() (CC)",
"io with cache components should work in pages router with getServerSideProps (CC)",
"io with cache components should work in pages router with getStaticProps (CC)",
"io without cache components should be a no-op during prerender without cache components",
"io without cache components should work in pages router with React.use()",
"io without cache components should work in pages router with getServerSideProps",
"io without cache components should work in pages router with getStaticProps"
],
"failed": [],
"pending": [],
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment