next.js: Boundary Serialization - `Props must be serializable for components in "use client" file` warning
Link to the code that reproduces this issue
https://github.com/inducingchaos/riley-barabash
To Reproduce
(Ignore code repro - SEE https://github.com/vercel/next.js/discussions/46795)
In my experience: just create any component in a "use client" file that accepts a function, dispatch for state, or anything that is non-serializable as props.
Current vs. Expected behavior
Current: Typescript (Next.js version) will give a warning (the title) to either a) make props serializable, or b) to postfix the prop name with ‘Action’. This has led to an unnecessary amount of renamings simply to avoid this warning - where the majority of cases don’t have anything to do with Server Actions at all.
Expected: No warnings when passing props unrelated to SA’s or the client-server boundary, especially in cases where client components are layered.
Provide environment information
Operating System:
Platform: darwin
Arch: x64
Version: Darwin Kernel Version 24.0.0: Mon Aug 12 20:54:30 PDT 2024; root:xnu-11215.1.10~2/RELEASE_X86_64
Available memory (MB): 32768
Available CPU cores: 16
Binaries:
Node: 22.9.0
npm: 10.8.3
Yarn: N/A
pnpm: 9.12.0
Relevant Packages:
next: 15.1.1-canary.16 // There is a newer canary version (15.1.1-canary.22) available, please upgrade!
eslint-config-next: 14.2.11
react: 19.0.0-rc-603e6108-20241029
react-dom: 19.0.0-rc-603e6108-20241029
typescript: 5.6.2
Next.js Config:
output: N/A
Which area(s) are affected? (Select all that apply)
Developer Experience, Linting, Partial Prerendering (PPR)
Which stage(s) are affected? (Select all that apply)
next dev (local)
Additional context
Didn’t provide a repro because I’m lazy and I think there’s enough context within the discussion thread I linked.
About this issue
- Original URL
- State: open
- Created 2 years ago
- Reactions: 8
- Comments: 32 (10 by maintainers)
This warning breaks my mental model of React composition. It relies on the fact that a component knows how a parent is using it. But shouldn’t it be the other way around?
If my client component is used by other client components, the props don’t have to be serializable, right? So this is only a real warning if a server component is using my client component.
Suggestion: Conceptually it would make sense for me to show this warning the other way around. So when using the client component in a server component, it should show a warning like “You cannot use a non-serializable prop” when trying to pass something to the client component.
If you have some component that’s sometimes used in both contexts (e.g. used from the server without passing functions down, but used from the client with function props), then you can fix this by creating a wrapper component that doesn’t take nonserializable props (for the server usage) and moving
'use client'to the wrapper.In the above example, the server can import
Foobecause its props are serializable. That’s where'use client'goes.The server cannot import
Bardirectly but that’s good because otherwise there’d be no way to passonClickto it.The idea is just that you designate some files as “client entry points” (they commit to keeping their props serializable), and that’s where
'use client'goes. And then the rest doesn’t have'use client'at all. And if some parts are used in both contexts, you probably just want to split out the “entry point” to show “how to render it” from the server.“use client” should be used only for marking the boundaries between client-server code - similarly to “use server”. Not every client component should be marked with it. Boundaries have additional restrictions, e.g. serializable props you mentioned
There is a label that “this component uses Hooks”. That label is
import { useState }etc.I don’t mean this as a troll. The import itself is literally what you’re asking for — it’s enforced at build-time that importing Hooks would fail the build in the Server world. That’s the highest level of assertion you can have. There’s nothing adding an additional directive would do.
Moreover, there is
import "client-only"which serves the same purpose (failing the build) for arbitrary non-React code. (Conceptually, you can think ofuseStatemodule inside React containingimport "client-only".) I would not recommend adding it everywhere in addition to importinguseStatethough because it’s superfluous.To mark that your component uses Hooks, it’s enough to import those Hooks. That is the purpose of the import syntax in the JavaScript module system.
The server/server imports and client/client imports are already well-served by the JavaScript module system. Imagine you have two separate JS apps — a backend and a frontend. Naturally, each of those apps can use imports normally to express the module dependencies within backend and frontend apps, respectively. It’s only when you want to cross the app boundary (server to client or client to server) that you need to use a directive.
The problem here seems very simple: we have 3 boundaries (server/server, server/client, client/client) and only 2 labels (“use client” and “no label”).
Leaving client/client components unlabelled is not a good solution. It ignores the fact that “use client” is also a declaration that “this component uses hooks, etc” in the eyes of basically every dev. Devs want to know immediately whether the components in a file are server-only or not—using “no label” for server/server and client/client is inherently ambiguous.
If NextJS intend to ship linter rules like this one, why not support a custom NextJS directive that is ignored by tools but allows devs to continue ‘labelling’ their client components as such. This label could be stripped out without any concerns since it is not used by React, but could be used to make NextJS linter rules more intelligent.
Won’t that create additional cognitive overhead since you now have to think what props suggested by autocomplete are allowed depending on the context? Since you only have to author a component once, but use it at least once, I’d rather make usage easier than authoring.
The problem is that we can’t check callsites since those might not have any directives and then it becomes really hard to check if this is a legit usage (both for human and compiler)
That’s easy to say, and has been said - but it doesn’t make a lot of sense in practice (or in this context), nor is it a viable solution to this problem.
First of all: I think that’s a great model, and if this philosophy was more deeply & widely propagated (more importantly - the parts of the framework that actively oppose and prevent this are changed/fixed) it could work.
Model 1: What You’re Suggesting
Benefits
Caveats
Model 2: How 88% of Next.js devs use
"use client"Benefits
Why This Warning Does NOT Make Sense
Proposed Solution
We need to make a unanimous decision on which model to follow, and fix all parts of the framework, docs, and the understanding of the community accordingly.
There is clearly a misalignment here in both the judgement of internal contributors (hence the linting <> rule conflicts) and the way Next.js is being consumed.
Fix the thinking, then fix the details. This frustrating “warning” is clearly a manifestation of the conflict between these two different philosophies.
Conclusion
I see the need to prevent non-serializable props from crossing the client-server boundary — but this can’t be the best solution. Using the model suggested here & in the discussion creates more warnings, errors, and headaches that will likely resurface in the future. This needs to be given a deeper consideration.
Mate really did just not read the ‘or any other hook’ in my message
This isn’t about
useStatespecifically. The compile-time enforcement I refer to above works for any other Hooks that aren’t supported in the Server world (likeuseEffect), and yes, it does work transitively (so it also works for custom Hooks).It works transitively because
importworks transitively. As soon as you bring a Client-only Hook into the build, it will cause a build failure if you’re in the Server world. That already works, and has always worked.It’s not a fix. This is just a linter rule bug that it doesn’t catch the other case. It has no relation to the actual problem.
No, the mental model is that
"use client"more or less means “export for server”.It’s kind of like you have
publicvsfriendvsprivatein some other languages."use client"means “my props being serializable is a part of my API contract that I intend to uphold”.So it doesn’t mean the component “knows” how it’s being consumed. It means that it declares — “I am here to serve as an entry point into the client stuff”.
This should not have a warning
The fact that changing the type to
onEmojiSelect(emoji: string): voidmakes the warning go away means this is all totally weird… Remove the warning