Unverified Commit 9f2779ec authored by Josh Story's avatar Josh Story Committed by GitHub

remove flag guarding `unstable_io` (#92923)

removes the flag guarding `unstable_io`.

The API isn't likely to change semantic meaning but could still be
removed. Do not rely on it extensively yet
parent 3d3def23
---
title: unstable_io
description: API Reference for the unstable_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()`.
```ts filename="app/page.tsx" switcher
import { unstable_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()
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
const orders = await db.query('SELECT * FROM orders LIMIT 10')
return (
<main>
<p>Generated at: {now}</p>
<ul>
{orders.map((order) => (
<li key={order.id}>{order.name}</li>
))}
</ul>
</main>
)
}
```
```js filename="app/page.js" switcher
import { unstable_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()
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
const orders = await db.query('SELECT * FROM orders LIMIT 10')
return (
<main>
<p>Generated at: {now}</p>
<ul>
{orders.map((order) => (
<li key={order.id}>{order.name}</li>
))}
</ul>
</main>
)
}
```
## How is this different from `connection()`?
[`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`.
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.
## Reference
### Type
```ts
function unstable_io(): Promise<void>
```
### Parameters
- The function does not accept any parameters.
### Returns
- A `Promise<void>` that resolves immediately during a real request or inside a cache scope, and suspends indefinitely during prerendering to prevent static output from including IO-dependent content.
## 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.
### Version History
| Version | Changes |
| --------- | -------------------- |
| `v16.x.x` | `unstable_io` added. |
...@@ -247,7 +247,6 @@ export function getDefineEnv({ ...@@ -247,7 +247,6 @@ export function getDefineEnv({
config.experimental.dynamicOnHover config.experimental.dynamicOnHover
), ),
'process.env.__NEXT_USE_OFFLINE': Boolean(config.experimental.useOffline), 'process.env.__NEXT_USE_OFFLINE': Boolean(config.experimental.useOffline),
'process.env.__NEXT_UNSTABLE_IO': Boolean(config.experimental.unstableIO),
'process.env.__NEXT_PREFETCH_INLINING': Boolean( 'process.env.__NEXT_PREFETCH_INLINING': Boolean(
config.experimental.prefetchInlining config.experimental.prefetchInlining
), ),
......
...@@ -9,11 +9,5 @@ const resolvedIOPromise: Promise<void> = Promise.resolve(undefined) ...@@ -9,11 +9,5 @@ const resolvedIOPromise: Promise<void> = Promise.resolve(undefined)
* prerender context so we always resolve immediately. * prerender context so we always resolve immediately.
*/ */
export function unstable_io(): Promise<void> { export function unstable_io(): Promise<void> {
if (!process.env.__NEXT_UNSTABLE_IO) {
throw new Error(
'`unstable_io()` requires the `experimental.unstableIO` option to be enabled in your Next.js config.'
)
}
return resolvedIOPromise return resolvedIOPromise
} }
...@@ -223,7 +223,6 @@ export const experimentalSchema = { ...@@ -223,7 +223,6 @@ export const experimentalSchema = {
partialFallbacks: z.boolean().optional(), partialFallbacks: z.boolean().optional(),
dynamicOnHover: z.boolean().optional(), dynamicOnHover: z.boolean().optional(),
useOffline: z.boolean().optional(), useOffline: z.boolean().optional(),
unstableIO: z.boolean().optional(),
optimisticRouting: z.boolean().optional(), optimisticRouting: z.boolean().optional(),
varyParams: z.boolean().optional(), varyParams: z.boolean().optional(),
prefetchInlining: z prefetchInlining: z
......
...@@ -427,7 +427,6 @@ export interface ExperimentalConfig { ...@@ -427,7 +427,6 @@ export interface ExperimentalConfig {
partialFallbacks?: boolean partialFallbacks?: boolean
dynamicOnHover?: boolean dynamicOnHover?: boolean
useOffline?: boolean useOffline?: boolean
unstableIO?: boolean
optimisticRouting?: boolean optimisticRouting?: boolean
varyParams?: boolean varyParams?: boolean
prefetchInlining?: prefetchInlining?:
...@@ -1841,7 +1840,6 @@ export const defaultConfig = Object.freeze({ ...@@ -1841,7 +1840,6 @@ export const defaultConfig = Object.freeze({
partialFallbacks: true, partialFallbacks: true,
dynamicOnHover: false, dynamicOnHover: false,
useOffline: false, useOffline: false,
unstableIO: false,
varyParams: false, varyParams: false,
prefetchInlining: true, prefetchInlining: true,
preloadEntriesOnStart: true, preloadEntriesOnStart: true,
...@@ -1988,7 +1986,6 @@ export interface NextConfigRuntime { ...@@ -1988,7 +1986,6 @@ export interface NextConfigRuntime {
| 'staleTimes' | 'staleTimes'
| 'dynamicOnHover' | 'dynamicOnHover'
| 'useOffline' | 'useOffline'
| 'unstableIO'
| 'optimisticRouting' | 'optimisticRouting'
| 'inlineCss' | 'inlineCss'
| 'prefetchInlining' | 'prefetchInlining'
...@@ -2056,7 +2053,6 @@ export function getNextConfigRuntime( ...@@ -2056,7 +2053,6 @@ export function getNextConfigRuntime(
staleTimes: ex.staleTimes, staleTimes: ex.staleTimes,
dynamicOnHover: ex.dynamicOnHover, dynamicOnHover: ex.dynamicOnHover,
useOffline: ex.useOffline, useOffline: ex.useOffline,
unstableIO: ex.unstableIO,
optimisticRouting: ex.optimisticRouting, optimisticRouting: ex.optimisticRouting,
inlineCss: ex.inlineCss, inlineCss: ex.inlineCss,
prefetchInlining: ex.prefetchInlining, prefetchInlining: ex.prefetchInlining,
......
...@@ -25,12 +25,6 @@ const resolvedIOPromise: Promise<void> = Promise.resolve(undefined) ...@@ -25,12 +25,6 @@ const resolvedIOPromise: Promise<void> = Promise.resolve(undefined)
* request and can be used freely inside cache scopes and client components. * request and can be used freely inside cache scopes and client components.
*/ */
export function unstable_io(): Promise<void> { export function unstable_io(): Promise<void> {
if (!process.env.__NEXT_UNSTABLE_IO) {
throw new Error(
'`unstable_io()` requires the `experimental.unstableIO` option to be enabled in your Next.js config.'
)
}
const workStore = workAsyncStorage.getStore() const workStore = workAsyncStorage.getStore()
const workUnitStore = workUnitAsyncStorage.getStore() const workUnitStore = workUnitAsyncStorage.getStore()
......
...@@ -3,9 +3,6 @@ ...@@ -3,9 +3,6 @@
*/ */
const nextConfig = { const nextConfig = {
cacheComponents: true, cacheComponents: true,
experimental: {
unstableIO: true,
},
} }
module.exports = nextConfig module.exports = nextConfig
/** /**
* @type {import('next').NextConfig} * @type {import('next').NextConfig}
*/ */
const nextConfig = { const nextConfig = {}
experimental: {
unstableIO: true,
},
}
module.exports = nextConfig module.exports = nextConfig
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