Docs: "server-only" package is referenced, but not documented

[petetnt]

What is the documentation issue?

Package server-only has no documentation and it's hard to say if it's a official package, or unofficial one, or recommended one. It's also very hard to say where it's sourced from without extensive detective work. It's being used both in NextJS docs as well as react.dev documentation.

The package should be documented, most likely owned one of the orgs and the source should be clearly available.

Is there any context that might help us understand?

This issue is about general confusion about server-only package.

Everything probably starts somewhere around https://github.com/reactjs/rfcs/blob/main/text/0227-server-module-conventions.md where Ryo and Dan have a propsal around server-module-conventions. It describes poisoning imports using a package.

At the same time, https://www.npmjs.com/package/server-only/v/0.0.1 is published to npm by @sebmarkbage , that contains absolutely no documentation and points to reactjs.org, making it seem that it's somehow related to React itself, despite not living under any Meta related namespace.

There's two usages of the package documented very loosely on the internet, first one can be found in the NextJS docs that clearly says that "install this package, use it like this", and it's probably fine: https://nextjs.org/docs/app/building-your-application/rendering/composition-patterns#keeping-server-only-code-out-of-the-client-environment

Closest thing to the source code is probably this pull request in NextJS #44861 that brings those imports to the NextJS codebase, the actual source code of server-only seems to match that, despite different author and being released a year before the package. Maybe I am missing something here?

Finally in the react.dev docs itself, server-only is used as a concept, but also as an actual package in https://react.dev/reference/react/experimental_taintUniqueValue#using-server-only-and-taintuniquevalue-to-prevent-leaking-secrets

Ideally, secrets like this are abstracted into a single helper file that can only be imported by trusted data utilities on the server. The helper can even be tagged with server-only to ensure that this file isn’t imported on the client.

Does the docs page already exist? Please link to it.

https://nextjs.org/docs/app/building-your-application/rendering/composition-patterns#keeping-server-only-code-out-of-the-client-environment

[samcx]

@petetnt Thank you for submitting an issue!

We will take a look at this soon to see how we can document this better

[a-rebets]

bumping this

[binishjoshi]

Bumping this again

[Zinnavoy]

Bumping this.

I must say, without documentation and seeing "Last Updated 3 years ago" makes it even harder to tell if it's official, if it does what it should do (whatever it is if you just stumbled upon it).

[ValentinGurkov]

Bumping this.

I must say, without documentation and seeing "Last Updated 3 years ago" makes it even harder to tell if it's official, if it does what it should do (whatever it is if you just stumbled upon it).

I don't know about official or not, but the package is more or less 1 line of code, so it does not really need any further updates. I agree that documentation is severely lacking.

[Zinnavoy]

Bumping this.
I must say, without documentation and seeing "Last Updated 3 years ago" makes it even harder to tell if it's official, if it does what it should do (whatever it is if you just stumbled upon it).

I don't know about official or not, but the package is more or less 1 line of code, so it does not really need any further updates. I agree that documentation is severely lacking.

Yes, I didn't mean it as in it's outdated but from someone new to Next this could easily be interpreted as such without documentation about the package.

[yasinelbuz]

Bumping this again

[icyJoseph]

Dan has written about both server-only and client-only packages. These packages, are more of an assertion:

The import 'client-only' and import 'server-only' poison pills that let some individual modules declare they must not be brought into the other world.

• https://overreacted.io/how-imports-work-in-rsc/

I'll look into adding some more info about server-only, and client-only, from Next.js' side of things.