[poll] Next.js integration package names and versioning

[siriwatknp]

A continuation from #34575 (comment)

We need to decide on the package names and versioning strategy for Next.js integration (as part of the OKR). Feel free to add more options as you see fit.

How many packages

Option 1: single package with subfolders

import { Link, Image,  } from '@mui/$name/material-ui'
import { Link, Image,  } from '@mui/$name/material-ui-v4'
import { Link, Image,  } from '@mui/$name/joy-ui'
import { Link, Image,  } from '@mui/$name/system'

Option 2: multiple packages

• system integration: this package will include API for integrating SSR and App router with the MUI system
• Material UI integration: reexport from system integration and a Link component.
• Joy UI integration: reexport from system integration and a Link component.

Package names

I think regardless of the option we decide on, it should have nextjs as part of the name.

Option 1

combination of the package

• @mui/system-nextjs
• @mui/material-nextjs
• @mui/joy-nextjs

Option 2

contains plugin in the name

• @mui/core-plugin-nextjs
• @mui/joy-plugin-nextjs
• @mui/material-plugin-nextjs
• @mui/system-plugin-nextjs

Versioning

Option 1

Follows Next.js, so the package will start with 14.0.0

Option 2

Follows MUI, so the package will start with 5.0.0

Independent

Starts with 1.0.0 or even 0.1.0

[siriwatknp]

I'd vote for:
No. of packages: option 1, I prefer a single package I think it is a lot easier to maintain and reason about
Package name: option 1, I think that this option is shorter and more straightforward than the other one.
Versioning: option 3, I think using an independent version gives the flexibility if either Next.js or MUI want to do breaking changes.

[Janpot]

As an end user, integrated in @mui/material-ui/nextjs would be the most ergonomic. Otherwise multiple packages. In terms of versioning, easiest for end users would be following MUI versions. Otherwise they'd have to look up a compatibility matrix every time a version changes. We could use peer dependency constraints or a runtime warning to check next.js version compatibility.

[Janpot]

But then, everyone installing @mui/material-ui will get it too.

next would be an optional peer dependency, so no extra dependencies needed, and the components themselves would be mostly wrappers around existing components, so not that much extra code added in the package. Install size (which currently is at 20MB) would likely not be significantly affected.

Bundles of end-users that don't use next would be unaffected as it'd be only provided as a package export. i.e. explicitly importing @mui/material/nextjs would be required.

That being said, the argument you make applies to "Option 1: single package with subfolders" as well. e.g. Under this option all @mui/material users would get the joy integration as well.

[siriwatknp]

I will create a POC for this approach.

[siriwatknp]

One question about this approach. How to support multiple versions of NextJS, eg. v13 and v14?

For example:

• Material UI v5.20.0 is compatible with Next.js v13
• Material UI v5.21.0 is compatible with Next.js v14

If I want to upgrade to v5.21.0 to get bug fixes or new features of Material UI and I want to keep using Next.js 13.

My assumption would be to have both?

• @mui/material/nextjs13
• @mui/material/nextjs14

[siriwatknp]

Also, the integration needs @emotion/server and @emotion/cache as dependencies. I don't see other ways apart from adding them as optional peer dependencies.

[Janpot]

if we want to avoid adding too many peer dependencies, or if we want to make the integration more straightforward we could use separate packages (@mui/material-nextjs) and use regular dependencies.
In terms of versioning I think what you propose here is the most flexible. e.g. with exports for next.js majors, @mui/material-nextjs/v13 and @mui/material-nextjs/v14. you can resolve @mui/material-nextjs to the latest nextjs version (at the time of publishing a @mui/material-nextjs major)

[oliviertassinari]

My take on it

How many packages

I think that at most one npm package would bring the best experience. I don't see why we would need more than one.

Now, I still think that we need a dedicated npm package, to help with the dependencies management.

Package names

@mui/plugin-nextjs We could have Material UI and Joy UI as different folders, same goes for different versions of Next.js

• @mui/plugin-nextjs/material-latest (alias)
• @mui/plugin-nextjs/material-v14
• @mui/plugin-nextjs/joy-latest (alias)
• @mui/plugin-nextjs/joy-v14

Versioning

I would match Material UI & Joy UI version (should be the same)

[siriwatknp]

I think appRouter (needs @emotion/cache) and pagesRouter (needs both cache and @emotion/server) needed to be split.

IMHO, it would be much simpler to go with @mui/material-nextjs since we are going to have just one styled-library anyway:

• @mui/material-nextjs/v13-appRouter
• @mui/material-nextjs/v13-pagesRouter
• @mui/material-nextjs/v13-Image
• @mui/material-nextjs/v13-Link

[oliviertassinari]

since we are going to have just one styled-library anyway

@siriwatknp Yes, but I wouldn't be surprised if each theme has its own npm package, like Joy Design and Material Design have today.

I think appRouter (needs @emotion/cache) and pagesRouter (needs both cache and @emotion/server) needed to be split.

It makes sense, so that we can use two different optional peer dependencies.