Note

This is a fork of next-superjson-plugin that adds support for the latest versions of Next.js.

Next SuperJSON Plugin

🔌 SuperJSON Plugin for Next.js (SWC)

Installation

Install packages first:

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

Add the plugin into next.config.js

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

Versions

package version	Next.js versions	notes
0.8.6	16.4.2 (SWC 79)	verified with the actual Next.js compiler
0.8.5	SWC 54 (target: 16.1.6)	incompatible with 16.4.2
0.8.4	^16.1.*
0.8.3	^15.4.* || ^16.0.*
0.7.*	^15.0.*	requires choosing router type (see release)

SWC plugin compatibility can change within a Next.js major version. This release uses ~16.4.2 as its Next.js peer range; the regression suite pins 16.4.2. Rerun the compiler tests before upgrading Next.js.

Testing and publishing locally

Use Node.js 22.12+ (required for the compiler tests), Bun 1.4.4, and Rust with the WASI target:

bun install --frozen-lockfile
rustup target add wasm32-wasip1
cargo test --locked
bun run test:compiler
npm publish --dry-run --access public

The compiler suite rebuilds and packages the WASM, then checks Pages Router wrappers, Date/BigInt JSON transport, excluded props, redirects, and App Router transforms and runtime decoding. Generated dist files are included in npm and ignored by Git.

To publish the prepared release locally:

npm publish --access public

The prepublishOnly hook runs the Rust tests and compiler suite before publishing. The GitHub publishing job is disabled; releases are published locally.

Usage

/pages (Pages Directory)

// For pages router no further configuration is required.

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 />;
}

Options

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

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

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

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

Loading

Bug Report

⚠️ Keep in mind: SWC Plugin is still an experimental feature for Next.js

Compatibility is verified against the pinned Next.js version listed above.

Leave an Issue

Special Thanks

• kdy1 (Main creator of swc project)