'use server' vs import 'server-only'

[lamualfa]

Questions

• What is the difference between 'use server' and import 'server-only'?
• When to use 'use server' and when to use import 'server-only'?
• Can one of them replace the other?

---

Examples

'use server'

Inside Server Action within Server Component

export default function Page() {
  async function create(formData: FormData) {
    'use server'
 
    // mutate data
    // revalidate cache
  }
 
  return <form action={create}>...</form>
}

import 'server-only'

Inside Function

import 'server-only'
 
export async function getData() {
  const res = await fetch('https://external-service.com/data', {
    headers: {
      authorization: process.env.API_KEY,
    },
  })
 
  return res.json()
}

---

References

'use server'

• https://react.dev/reference/react/use-server

import 'server-only'

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

---

@sebmarkbage @ijjk @timneutkens @Timer @rauchg @leerob

[icyJoseph]

server-only is to poison a module, so that if a client module, imports from it, the application crashes. An error is raised.

use server is used to mark code as executable server side:

"use server" ensures this function is only ever executed on the server.

When you use use server, at module level, all of the functions opt-in into the behavior above.

[jd-carroll]

Thank you, it is starting to become more clear and I think I get it now.

Though, I think I need to reflect on this a bit:

modules are by default server components.

If you have a server component that renders a client component, it has 'use client', and you want to trigger server side work, from that client component, you can use 'use server' in an async function, as an escape hatch from the client module, that'll allow you to call this function in the server, rather.

You can hoist the "use server" directive to the top of a module, to make all function exports executable from the client, but actually run on the server.

Reflection:

• Modules default to server components -> sure
• A server component that renders a client component -> I somewhat read this as if a React Component / Fragment was returned from the function and has nothing to do with whether or not there is a 'use client' at the top of the module ... but ... I think that is incorrect since you wrote "... , it has 'use client'".
• From that client component, you can use 'use server' in an async function as an escape hatch -> Sure that make sense, but in this example the 'use server' is within (each) async function
• You can hoist the 'use server' directive to the top of the module -> This is where I am really getting lost. Is that to say you can have both 'use client' and 'use server' at the top of a [file] module?

[icyJoseph]

Modules default to server components -> sure

So, unless you slap a use client at the top of a file, that won't ever be bundled into JavaScript that's send to the client.

A server component that renders a client component -> I somewhat read this as if a React Component / Fragment was returned from the function and has nothing to do with whether or not there is a 'use client' at the top of the module ... but ... I think that is incorrect since you wrote "... , it has 'use client'".

Say you have module A, which is a server component, and module B has a use client directive.

In module B you have a Button component. Then you can import the Button into module A. The bundler knows that the code to render the Button has to also be sent the client.

So React builds up two trees, a server tree, and a client tree, and calculates an initial HTML frame to send to the client based on them. In the client, the JS for the Button is downloaded, (note that this might include utils, helpers, etc), and hydration happens where React replays rendering the Button, on the client and matches the trees.

• Why do Client Components get SSR'd to HTML? reactwg/server-components#4

This is a rough explanation, I'd recommend reading more about this in react.dev, or the next.js docs. I think this talk can also help out a lot: https://www.youtube.com/watch?v=36uY-c0E_EQ

From that client component, you can use 'use server' in an async function as an escape hatch -> Sure that make sense, but in this example the 'use server' is within (each) async function

Right so here, you define a function, and in that function's body, you slap a use server this means this function will run server side, when called from the client. What you do is you define this typically, within a Server component, and then either pass it as props, or by exporting it, into a client component.

If we deviate an take a look at this list: https://react.dev/reference/react/use-server#serializable-parameters-and-return-values

We see, that functions that are server actions are considered serializable, that is, can be passed to a client, but functions which are not, are not considered serializable.

You can hoist the 'use server' directive to the top of the module -> This is where I am really getting lost. Is that to say you can have both 'use client' and 'use server' at the top of a [file] module?

This is more of a quality of life enhancement. Since you can collect a bunch of actions into a file, and don't need to tag them all, just put the directive at top of the file.

I think maybe a bit of confusion comes from thinking that you can define the server action in client code directly, I'll reformulate that bit in my answer. You can only define server actions, in server code, but the directive allows you to call them from the client.

I was mostly answering about the difference between server-only and use server.

[ys-oo]

@icyJoseph hey man i did read react js source code before , so i can call myself a semi-nerd :) , and i also can say that you are the best one to explain these concepts to beginners , I'm coming here from a good search to see if someone had this question. you are a legend my friend. i wish you all the best of luck

[gcb]

So to wrap this up... using use server at the top of the file, is just a shortcut to adding use server inside all function on that file, and it does nothing else besides that? and it will still send the signature of each of those server actions, and allow the function to be called from the client with an exposed api?

while import 'server-only' will never expose anything of the method to the client and can only be called from the body of other functions being executed on the server?

[icyJoseph]

while import 'server-only' will never expose anything of the method to the client and can only be called from the body of other functions being executed on the server?

More like, import 'server-only' will cause errors. Like during development, if this code is used within Client Module umbrella, things will break. Same during build time.

[Senbonzakura1234]

server-only is to poison a module, so that if a client module, imports from it, the application crashes. An error is raised.

use server is used to mark code as executable server side:

"use server" ensures this function is only ever executed on the server.

When you use use server, at module level, all of the functions opt-in into the behavior above.

@icyJoseph
Okay so it seems you have a gist of how server-only works, can you elaborate me how to fix this problem of mine? I'm trying to do some seeding and migration files and running them using tsx package, but when i run the command it throwed by the server only package because the seed file is importing code from file that importing the server only package.

Is there anyway to work around this?

[icyJoseph]

Without a repository, it is hard to tell, but I can speculate that you might be directly, or indirectly, importing the server-only into a client module. Note that this can be done through indirect imports, which are slightly harder to notice.

[Senbonzakura1234]

@icyJoseph
here is my code

The code I'm import from is a database connection code, so there is no way it was mingle with any client code, i can say that for sure since when i run the app normally with next start or next dev, there is no error bubble up, it just throw where i run that single file with tsx cli

[icyJoseph]

Aha, I did not understand that you use a different command, that's where the problem is.

Similarly, in Jest, even if you tell Jest to run the test in Node.js env, it might crash, because server only is, in a more strict fashion, ensuring that the code runs within Server Components, not a Node.js server necessarily. Take a look at the package.json of server-only:

{
  "name": "server-only",
  "description": "This is a marker package to indicate that a module can only be used in Server Components.",
  "keywords": [
    "react"
  ],
  "version": "0.0.1",
  "homepage": "https://reactjs.org/",
  "bugs": "https://github.com/facebook/react/issues",
  "license": "MIT",
  "files": ["index.js", "empty.js"],
  "main": "index.js",
  "exports": {
    ".": {
      "react-server": "./empty.js",
      "default": "./index.js"
    }
  }
}

The important part are the exports, so the bundler that's doing Server Components, would pick up on react-server, which is an empty file, but a bundler that's not doing react-server, would pick up the file that throws. That's what's happening to you... now the question is, how can you tell your CLI that you want to pick up react-server, from server-only...

[Senbonzakura1234]

My current solution is conditionally import server only with some env variables, which i have to use import() function call, is it safe to use? It works but not sure i could use it in prod.

[Senbonzakura1234]

hi @icyJoseph do you know anyway to get around this? my solution is to conditionally importing server only, but I'm not sure it's okay in production, need your advice.

Tks