Next.js example is confusing

The current Next.js example is quite daunting with several files and concepts thrown in. I will apologize in advance because the following may seem like a bit of a rant, but I really want to improve these examples.

Things I found confusing

The whole example looks more like someone’s personal boilerplate for their production app rather than an example for people to learn the API and get productive quickly.

Here are some of the things that are confusing to me:

• What does getContext.js do and why is it in a /styles folder?
• What does “context” mean in this instance?
• withRoot.js is a bit confusing, why is there mutation here? Is it only for the sake of adding a displayName?

  let AppWrapper = props => props.children;
  AppWrapper = withStyles(styles)(AppWrapper);
  

• Is it possible to use Material-UI without using so many HOCs? What about a render-prop pattern instead? There’s a lot of in-direction here that I suspect may not be completely required.

JSS confusion

On top of that, there’s the JSS barrier to entry:

• Why is JSS necessary for this example? I can guess that it has something to do with server-side rendering, but it’s not made clear how it’s working. There are many moving parts here.
• jss, react-jss, jss-preset-default are all dependencies mentioned in the code but do not exist inside package.json.
• You have to learn about sheetsManager, sheetsRegistry, and a lot of other jargon that many React devs may not be immediately familiar with.

Having to learn how to work with three new dependencies in addition to your UI library is not exactly the easiest way to get started if all I want is a simple colored button.

Concepts unrelated to Material-UI

There are also random things thrown in that are not directly related to Material-UI, here are a couple examples:

• custom meta tag with the hint: “Use minimum-scale=1 to enable GPU rasterization”
• PWA stuff (manifest.json + setting the PWA color for icons)

Conclusion

I know it’s probably a little too late to change the API for the 1.0 release, but we can do our best to make it easier for people to learn. I mean, all I honestly wanted to do was to use Next.js with Material-UI and have a custom color. It shouldn’t require learning all of the things above.

There are a few things we can do:

1. Separate the example into several separate examples show-casing each individual feature.
2. Thoroughly document and explain the example in a separate README or blog post.
3. Simplify the API so that usage is also likewise simplified.
4. Offer higher level abstractions/helper functions (they might be less powerful, but they will be easier for users to get started)

[adrianmcli]

@glenarama @oliviertassinari

I hacked an example together real quick. Not sure how correct or good it is, but here it is: https://github.com/adrianmcli/styled-mui-next

I feel like getPageContext.js and withRoot.js might benefit from being abstracted away into a library, but I’m not sure.

Let me know what you guys think. Let’s try to improve it together.

[oliviertassinari]

@gauravdhiman Please ask the question on Next.js side. There is a head component for this use case.