next-superjson-plugin's Introduction

Next SuperJSON Plugin

🔌 SuperJSON Plugin for Next.js (SWC)

/pages (Pages Directory)

export default function Page({ date }) {
  return <div>Today is {date.toDateString()}</div>;
}

// You can also use getInitialProps, getStaticProps
export const getServerSideProps = () => {
  return {
    props: {
      date: new Date(),
    },
  };
};

Allows pre-rendering functions to return props including Non-JSON Values(Date, Map, Set..)

/app (App Directory)

// Use "data-superjson" attribute to pass non-serializable props to client components
// No needs to change the propsType of Client Component (It's type-safe!)

export default function ServerComponent() {
  const date = new Date();
  return <ClientComponent date={date} data-superjson />;
}

Provides data-superjson attribute for Server Component > Client Component Serialization.

Usage

Install packages first:

npm install superjson next-superjson-plugin
# or Yarn
yarn add superjson next-superjson-plugin

Add the plugin into next.config.js

// next.config.js
module.exports = {
  experimental: {
    swcPlugins: [["next-superjson-plugin", {}]],
  },
};

Options

You can use the excluded option to exclude specific properties from serialization.

['next-superjson-plugin', { excluded: ["someProp"] }],

How it works

sequenceDiagram
    participant Next.js
    participant SWC Plugin
    participant SuperJSON
    Next.js->>SWC Plugin: Request Transform
    SWC Plugin->>SWC Plugin: Transform Pages/Components <br> To Use SuperJSON
    SWC Plugin->>Next.js: Take Modules
    Next.js-->SuperJSON: Connected
    Next.js->>SuperJSON: Serialize Props <br> (Date, BigInt, Set, Map..)
    Note over SWC Plugin: getInitialProps <br> getServerSideProps <br> getStaticProps <br> Server Components
    SuperJSON->>Next.js: Deserialize Props
    Note over SWC Plugin: Pages <br> Client Components