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.

See: https://github.com/vercel/next.js/discussions/46795

About this issue

  • Original URL
  • State: open
  • Created 2 years ago
  • Reactions: 8
  • Comments: 32 (10 by maintainers)

Most upvoted comments

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.

'use client'

import { Bar } from './Bar'

// everything here is serializable
export function Foo({} : {}) {
  return <Bar />
}
// onClick is optional but not serializable
export function Bar({ onClick }: { onClick?: () => {} }) {
  return <div onClick={onClick} />
}

In the above example, the server can import Foo because its props are serializable. That’s where 'use client' goes.

The server cannot import Bar directly but that’s good because otherwise there’d be no way to pass onClick to 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

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”

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 of useState module inside React containing import "client-only".) I would not recommend adding it everywhere in addition to importing useState though 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 problem here seems very simple: we have 3 boundaries (server/server, server/client, client/client) and only 2 labels (“use client” and “no label”).

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

"use client" should be used only at the boundary where a client component is installed in a server-first architecture - almost like an “escape hatch” in a similar way to how Server Actions are used.

Benefits

  • Further framework/build optimizations??? Personally, I think this should be implemented on a compiler level, where Next.js just knows where the boundary is.
  • DX gain because the boundary is clearly marked? This seems minimal to me. Using unlabeled components (see below) throws all of these gains out the window.
  • A distinction to disallow non-serializable props? This additional “layer” seemingly creates more DX complications than UX errors. This can/should be solved in other ways.

Caveats

  • No clear distinction between server and client components IF it’s not a boundary component. Requires more structural overhead and creates a “third” type of file (that which is a client component, but unlabeled). It’s unintuitive.
  • Unlabeled Client Components behave like Server Components - try using Framer Motion, useEffect, or useState in one of these. In my experience, you can’t.

Model 2: How 88% of Next.js devs use "use client"

"use client" (a client component) is antonymous to no declaration (a server component) and is used to send JS to the client, rather than pre-compiled HTML.

Benefits

  • Clear distinction between client/server: every component that needs this functionality is marked.
  • Easier to understand, already well understood.

Why This Warning Does NOT Make Sense

  • It can’t be disabled on a by-line or by-file basis like other TS/ESLint errors.
  • Even following Model 1, littering the codebase with ‘Action’ postfixes on props doesn’t make a lot of sense when 80% of error/warn cases are unrelated to Server Actions. The error is not intelligent enough to tell the difference between SA’s and functions like state setters, which makes the ‘Action’ postfix more irrelevant.

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

Assuming that every component uses useState only shows that you are being dogmatic. Custom hooks? Other useX hooks?

This isn’t about useState specifically. The compile-time enforcement I refer to above works for any other Hooks that aren’t supported in the Server world (like useEffect), and yes, it does work transitively (so it also works for custom Hooks).

It works transitively because import works 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.

Though I generally agree that the most common case (bumped into it 3 times in my project already) of prop: (data: T) => U being wrong and prop(data: T): U being fine is annoying and should be automatically fixed by the linter if it really is a fix to whatever problem the former typing causes.

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.

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?

No, the mental model is that "use client" more or less means “export for server”.

It’s kind of like you have public vs friend vs private in 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”.

"use client"

import * as React from "react"

import { Button } from "@/components/ui/button"
import {
    EmojiPicker,
    EmojiPickerContent,
    EmojiPickerFooter,
    EmojiPickerSearch
} from "@/components/ui/emoji-picker"
import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover"
import { SmileIcon } from "lucide-react"

export function EmojiPopover({
    onEmojiSelect
}: {
    onEmojiSelect: (emoji: string) => void
}) {
    const [isOpen, setIsOpen] = React.useState(false)

    return (
        <Popover onOpenChange={setIsOpen} open={isOpen}>
            <PopoverTrigger asChild>
                <Button size="icon">
                    <SmileIcon />
                </Button>
            </PopoverTrigger>
            <PopoverContent className="w-fit p-0">
                <EmojiPicker
                    className="h-[342px]"
                    onEmojiSelect={({ emoji }) => {
                        setIsOpen(false)
                        onEmojiSelect(emoji)
                    }}
                >
                    <EmojiPickerSearch />
                    <EmojiPickerContent />
                    <EmojiPickerFooter />
                </EmojiPicker>
            </PopoverContent>
        </Popover>
    )
}

This should not have a warning

The fact that changing the type to onEmojiSelect(emoji: string): void makes the warning go away means this is all totally weird… Remove the warning