Announcing carbon-tutorial-nextjs

[tay1orjones]

We're excited to share the newest iteration of our React tutorial, carbon-tutorial-nextjs. This is based on the previous tutorial you may have already taken, but has now been updated to use Next.JS instead of react-scripts (Create React App).

If you've taken the new tutorial, we're interested in knowing how your experience was. Please leave a comment below. We can funnel new ideas or problems into issues if necessary. Thanks for taking the Carbon React tutorial! 🥳

[PrettyLegit]

Hey IBM Carbon Team!

Question:

Is there a specific reason why the tutorial suggest newcomers to load all their page specific styles, mixins, and overrides into the global.scss. I know I can just take what I learned from the tutorial and change my project style architecture to fit my custom needs, but I curious as to why IBM Carbon Tutorial isn't opting to use the scss modules in the tutorials (next.js and CRA).

CSS modules reduces the need to "have good names" to avoid collisions with other pages that might use the same name and the bundle size per page would be smaller if we only ship the styles we need for a given page.

Please advise. Thank you in advance, I am an intern still learning my way around web dev :)

Bugs Encountered:

• src/app/home/_landing-page.scss
  Line 25 uses rem(-40px) which throw an error stating: SassError: 2 arguments required, but only 1 was passed.
  I just deleted the rem function. margin-top: 40px; Fixes it and allows me to run the branch v5 locally.

[tay1orjones]

Hey thanks for bringing this up! The primary reason is just for simplicity's sake. CSS Modules can sometimes be difficult to configure properly with the architecture of the sass provided through @carbon/react. It's easy to put yourself in a situation where you have duplicated styles. For this reason in all our examples we default to showing how to bring in all the Carbon styling that you need in one spot via

@use '@carbon/react';

[tay1orjones]

Also the rem function issue should now be fixed with the latest version of @carbon/react.

[m4olivei]

Hi there 👋 ! I just went through the Carbon Next.js tutorial. It was great! Thanks for putting it together. I found a few small things in the docs that were off. Nothing major, but might make the next persons read through a tad simpler. I'll title the below sections by the correspondning Tutorial step and list things I found.

Thanks to all those involved for putting this together!

Overview

• Yarn 1.x went in to maintenance Jan 2020, and will soon be end of life. It’s linked in the tutorial under Overview > Prerequisites > Yarn. Update to Yarn 3.x / 4.x?

Step 1

• In Step 1 under “Render the header”, this was confusing:

Next we’ll render our UI Shell by importing our TutorialHeader component and Content into a provider components in the Root Layout. We do this because layout components in Next.js 13 are server-side components.

• The tutorial assumes zero Next.js knowledge, but the last sentance here is a pretty big leap for me (have very little Next.js exposure). Is there a documentation reference we can link to that spells this out in more detail?
• The name “providers” sounds liks it might be something Next.js specific, especially since providers.js is placed at the same level as page.js and layout.js , which do have special meaning in Next.js. It doesn’t appear that Providers or providers.js is a Next.js specific convention. Taken together, I think this part could be easier to follow and less confusing.
  • As a suggestion, to help alleviate the confusion, rename Providers to something like PageWrapper and put it in the components directory, or at least rename providers.js to Providers.js to signal that it’s a component, similar to RepoTable.js later in the tutorial.
• Under “Create pages”

  In each there is a page.js and optionally a layout.js and styling sheet.

• Suggested update (base on):

  In each there is a page.js and optionally a layout.js and stylesheet.

• Under import and export content pages:

  Starting with LandingPage, just like with our header, we need to export the component in javascript path=src/app/home/page.js by adding

• There is some odd prefix in there, suggested update:

  Starting with LandingPage, just like with our header, we need to export the component in src/app/home/page.js by adding

• Under “Git commit and push”
  • I use Webstorm. I had to be careful to not commit my .idea directory. Suggest to add to tutorial’s .gitignore file.

Step 2

• Under “Add landing page grid”, I think there is a good opportynity here to link out to the Grid docs
• Noticed Carbon Dev Tools doesn’t work on this, any ideas why?

• Last sentance under Build repo page > Build data table:

  At this point, return to RepoPage because now we need to render a static RepoTable.

• Suggested change:

  At this point, return to src/app/repos/page.js because now we need to render a static RepoTable.

Step 3

• Under Fetch Data > Imports, there is a link to “React Hooks” and “useEffect” that goes to the old React docs. Should update to the new React docs.
• Same is true for other React docs references in the page.

Step 4

• Under Create components > Add files:

  Import _info.scss in app.scss after all of the tutorial-header.scss import.

• Suggested change:

  Import _info.scss in global.scss after the tutorial-header.scss import.

Step 5

Looking at package.json, you’ll find yarn build to run next build. This builds the app for production to the build folder.

• I don’t get a build folder. I’m new to Next.js, so not sure, but maybe these docs are relevant? I found that changing my next.config.js to the following, then re-running yarn build gave me a static build dir:

    /** @type {import('next').NextConfig} */
    const nextConfig = {
      output: 'export',
      distDir: 'build',
    };
    
    module.exports = nextConfig;

Wrapping up

If you want to show the world your new skills, you can share your deployed application and showcase the five pull requests you have completed …

• This tutorial only asked for 4 pull requests. The last was a suggestion to deploy the build, which does not result in a PR …

[tay1orjones]

Tons of feedback! Thank you so much. We'll work on incorporating this feedback into the tutorial. If you're keen, we'd also welcome a pull request for things like updating to yarn 4, tweaks to the docs on the website, or updates to the tutorial repo itself across all the different step branches.

[benoitclerget]

Hello, I have setup issues. The yarn install does not complete. See details below.
Is there a place to open such issues or using this comment is enough to get support?
Thanks in advance

I am running on Linux RHEL 8.8

:carbon-tutorial-nextjs$ node --version
v18.17.0
:carbon-tutorial-nextjs$ yarn --version
1.22.19

Error found while running yarn :

:carbon-tutorial-nextjs$ yarn install
yarn install v1.22.19
[1/4] Resolving packages...
warning @commitlint/cli > babel-polyfill > [email protected]: core-js@<3.23.3 is no longer maintained and not recommended for usage due to the number of issues. Because of the V8 engine whims, feature detection in old core-js versions could cause a slowdown up to 100x even if nothing is polyfilled. Some versions have web compatibility issues. Please, upgrade your dependencies to the actual version of core-js.
warning @commitlint/cli > babel-polyfill > babel-runtime > [email protected]: core-js@<3.23.3 is no longer maintained and not recommended for usage due to the number of issues. Because of the V8 engine whims, feature detection in old core-js versions could cause a slowdown up to 100x even if nothing is polyfilled. Some versions have web compatibility issues. Please, upgrade your dependencies to the actual version of core-js.
warning lint-staged > micromatch > snapdragon > [email protected]: See https://github.com/lydell/source-map-resolve#deprecated
warning lint-staged > micromatch > snapdragon > source-map-resolve > [email protected]: See https://github.com/lydell/source-map-url#deprecated
warning lint-staged > micromatch > snapdragon > source-map-resolve > [email protected]: https://github.com/lydell/resolve-url#deprecated
warning lint-staged > micromatch > snapdragon > source-map-resolve > [email protected]: Please see https://github.com/lydell/urix#deprecated
[2/4] Fetching packages...
error @ibm/[email protected]: The engine "node" is incompatible with this module. Expected version ">=14". Got "10.24.0"
error Found incompatible module.
info Visit https://yarnpkg.com/en/docs/cli/install for documentation about this command.

[benoitclerget]

oups... I tried to reinstall yarn (npm install --global yarn) and the yarn command succeeded...
So, sorry for this comment, my issue seems resolved

(Note: the yarn.lock file has been updated, is it expected?

[rubensdemelo]

Hi, I would like to know why the tutorial does not use Typescript. Thank you.

[tay1orjones]

Hi, using TypeScript in the tutorial would add an additional layer of complexity that isn't necessary to understanding how to use @carbon/react. For the tutorial we try to balance simplicity with a real-world context. It's the same reasoning for why there aren't any steps in the tutorial to write tests, for instance.

[tay1orjones]

Surfacing some feedback we received about Step 5:

• It's not clear that this is an optional step
• Deploying to GitHub pages requires some additional steps not outlined in the current docs:

  maybe add some instructions how deploy this app on GH pages, using SSG. Here is a commit you can base on, looks like this. You have to change the repo in the deploy script.
  Weirdest thing to me is, that I had to replace the tag from NextJS to get this working - it seems it can’t handle SSG that well or I’m missing something in the config (but was not mentioned in the docs). Also NextJS does not allow a relative basePath like ./

[tay1orjones]

Surfacing some feedback we received about complexity:

• Next.js is additional overhead not required to understand how to use Carbon components
• Consider refactoring the tutorial to not be next.js based or find a way to run it within an online coding editor such as codesandbox or stackblitz

This feedback is rooted in developers who are completing the tutorial as part of their onboarding process and are having difficulty completing the tutorial due to errors with yarn, running the project, unfamiliarity with next.js, etc.

Read the full conversation on internal slack