docs(rsc): document barrel package workaround for validate-imports

[hi-ogawa]

• related to fix(rsc): validate client-only/server-only imports after tree-shaking #1511
• related to validate-imports false positive on sideEffects:false barrels (unused leaf kills build) cloudflare/vinext#4007
• investigation notes: https://gist.github.com/hi-ogawa/ff662a548d746ed213ea441467bbeddc

A server component that imports one component from a UI library's barrel entry, such as import { Toast } from "@heroui/react", fails with 'client-only' cannot be imported in server build when an unused module the barrel re-exports imports client-only. #1511 moves the build check after tree-shaking, but dev still fails because Vite evaluates every module the barrel re-exports. In the heroui case, react-aria's top-level createContext crashes dev even when the check is disabled.

Rewriting barrel imports to subpath imports fixes both dev and build without changes to the plugin. This PR adds a README section on barrel packages that shows how to do it with @rolldown/plugin-transform-imports, lists the gotchas I hit, and points to a "use client" component when a subpath still reaches client-only code.

transformImports({
  'some-ui-library': {
    transform: [
      ['[A-Z].*', 'some-ui-library/{{kebabCase member}}'],
      ['*', 'some-ui-library'],
    ],
    skipDefaultConversion: true,
  },
})

The e2e test uses a synthetic sideEffects: false barrel package where a server component uses Button and an unused Calendar imports client-only:

	dev	build
without transform	fails	fails
with transform (Rolldown only)	renders	renders

For @heroui/react, I checked this setup on the reporter's repro with vinext 1.2.0 and plugin-rsc 0.5.38. Dev renders, and the build passes and renders in preview:

// vite.config.ts
import transformImports from '@rolldown/plugin-transform-imports'

export default defineConfig({
  plugins: [
    transformImports({
      '@heroui/react': {
        transform: [
          // `Skeleton` -> `@heroui/react/skeleton`
          ['[A-Z].*', '@heroui/react/{{kebabCase member}}'],
          ['*', '@heroui/react'],
        ],
        skipDefaultConversion: true,
      },
    }),
    tailwindcss(),
    vinext(),
  ],
})

// app/page.tsx (server component)
import { Skeleton } from '@heroui/react'
import { ToastProvider } from './toast-client'

export default function Page() {
  return (
    <main>
      <Skeleton />
      <ToastProvider />
    </main>
  )
}

// app/toast-client.tsx
'use client'
import { Toast } from '@heroui/react'

export function ToastProvider() {
  return <Toast.Provider />
}

Skeleton works through the barrel with the transform, because its subpath entry only reaches a "use client" module.

Toast is different, because the import that fails is inside heroui, so rewriting app imports can't reach it. In heroui 3.2.1 and react-aria-components 1.18.0, the chain is:

1. components/toast/index.js has no directive, so it is server code. It imports toast-queue.js to build the compound Toast object.
2. components/toast/toast-queue.js has no directive either. It imports UNSTABLE_ToastQueue from react-aria-components/Toast and creates a toastQueue instance at the module's top level.
3. react-aria-components/dist/exports/Toast.mjs has import "client-only", and it also imports the toast components, whose module calls createContext at the top level. That call throws under the react-server condition, which is the dev error.

The queue class itself comes from react-stately/useToastState and is safe on the server, but heroui imports it through react-aria-components' client-only entry. Tools disagree on this graph. Vite dev evaluates the entry and crashes, and Next's webpack build reports client-only. Next's Turbopack follows the re-export to react-stately and never evaluates the entry, and Rolldown drops the entry from the output, which is why the build passes with #1511. vinext#4099 gets Turbopack's result in Vite by rewriting heroui's import to react-stately in the rsc environment.

Which behavior is right is debatable:

• Rejecting it follows the packages' intent. react-aria-components put import "client-only" on the Toast entry on purpose, with a comment saying it should break RSC imports. heroui imports that entry from modules with no directive, which run on the server. Rejecting matches ESM evaluation and webpack, and it keeps dev and build consistent. The lenient result relies on the package's "sideEffects": ["*.css"], which declares the entry side-effect free even though its client-only import is a side effect by design. Under that reading, the marker can't fire for any named import. The entry defines nothing of its own, since all eight of its exports are re-exports plus the client-only import, so following re-exports skips it even for the components the marker is meant to keep out of rsc. Only a namespace, bare or dynamic import of the entry still hits it.
• Accepting it follows what actually runs. The only binding used is a plain state class that is safe on the server, so the marker covers more than it needs to. sideEffects explicitly allows skipping modules whose own exports are unused, and Turbopack, Next.js's default bundler, renders this page. But following re-exports is no safety net: a server component importing Collection from react-aria-components/Collection fails with createContext is not a function in Turbopack, a less clear error than client-only.

This PR keeps plugin-rsc's current behavior, rejecting it in both dev and build, and documents the "use client" wrapper as the user-side fix. The cleaner fix is upstream, either heroui importing ToastQueue from react-stately/useToastState or react-aria-components exporting the queue from an entry without the marker.