'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]

I still don't know that this answer helps answer the overall question.

If you focus on "module level" (though I think the more appropriate description would be "file level" since a module is more akin to a node module), how does 'use server' differ from import 'server-only';?

Give what you have written above:

• server-only is to poison a module, so that if a client module, imports from it, the application crashes

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

One of those statement must be incorrect. Because if server-only "is to poison a [file] module" then the implication is that you are able to import any "[file] module" into an other "[file] module" with a 'use client' at the top, regardless of whether the other file has a 'use server' at the top. Which is then in conflict with

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

So does 'use server' ensure the function is only ever executed on the server or are there exceptions?

If there are not exceptions, then how does import 'server-only' differ from 'use server' at a "[file] module" level?

[icyJoseph]

Let's take it from the practical angle, and one thing at a time.

Say you have a module that uses APIs that are only available server side, or that contains, sensitive but not secret information. In either case, sending the contents of this file/module to the client, would result in unwanted behavior. Either crashing at runtime, or by leaking the sensitivity data.

A way to prevent this at development and build time, is to import server-only in the module.

This will cause an error during dev time, in tests and at compile time, if the module has been imported, directly or indirectly into a client module.

What about 'use server'? Well it is more of a complement to 'use client', and the fact that modules are by default server components. Though, use server is only allow in server side code, not within use client modules.

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. Note that use server directive can only be used in server side code, but you can invoke a server action, from the client.

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.

For server only, you want to prevent leaking the module to the client, by taking a defensive approach. Throw if a client module ever touches the module.

For use server, you wanna escape from the client module, to invoke a server side function. And yes, a server component thay renders a form, can invoke a server action, through the action prop but it all happens client side.

[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

[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