diff --git a/README.md b/README.md index 81bd729bc98..467bd128634 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,9 @@ ![Deployment status](https://github.com/carbon-design-system/carbon-website/workflows/Deployment%20status/badge.svg) -This is the [Carbon Design System website](http://www.carbondesignsystem.com). It's built using the [gatsby-theme-carbon](https://gatsby-theme-carbon.now.sh/) with [GatsbyJS](https://www.gatsbyjs.org/). +This is the [Carbon Design System website](http://www.carbondesignsystem.com). +It's built using the [gatsby-theme-carbon](https://gatsby.carbondesignsystem.com/) +with [GatsbyJS](https://www.gatsbyjs.org/). ## πŸ“‚ Structure @@ -29,11 +31,14 @@ src - `lint:js` – lint your JavaScript files - `format` - run Prettier -If you need more detailed information on how to set up your machine to develop locally, please take a look at our [wiki](https://github.com/carbon-design-system/carbon-website/wiki). +If you need more detailed information on how to set up your machine to develop +locally, please take a look at our +[wiki](https://github.com/carbon-design-system/carbon-website/wiki). ## πŸš€ Build -Runing the build command generates all the files and places them in the `public` folder. +Running the build command generates all the files and places them in the +`public` folder. ``` yarn build diff --git a/src/pages/all-about-carbon/what-is-carbon.mdx b/src/pages/all-about-carbon/what-is-carbon.mdx index 473106c5f62..248681d729b 100755 --- a/src/pages/all-about-carbon/what-is-carbon.mdx +++ b/src/pages/all-about-carbon/what-is-carbon.mdx @@ -112,9 +112,10 @@ work and contribute patterns back to the system. ### We support adoption **We conduct training classes, run meetups, and offer certifications.**Β We offer -tutorials in Angular, React, and Vue. We run [meetups](/whats-happening/meetups) -and design reviews on a regular basis. We're also available to teach at -conferences, bootcamp labs, and wherever else we're needed. +tutorials in Angular, React using Next.js, and Vue. We run +[meetups](/whats-happening/meetups) and design reviews on a regular basis. We're +also available to teach at conferences, bootcamp labs, and wherever else we're +needed. **We engage the community.**Β We strive to be one of the world's best design systems and we’re diff --git a/src/pages/all-about-carbon/who-uses-carbon.mdx b/src/pages/all-about-carbon/who-uses-carbon.mdx index f6a703acf1f..f8956e80298 100755 --- a/src/pages/all-about-carbon/who-uses-carbon.mdx +++ b/src/pages/all-about-carbon/who-uses-carbon.mdx @@ -133,7 +133,7 @@ Here are some ways developers can begin engaging with Carbon. [design principles](https://www.ibm.com/design/language/). - Check out a tutorial in your framework of choice - ([React](/developing/react-tutorial/overview/), + ([React using Next.js](/developing/react-tutorial/overview/), [Angular (community)](/developing/angular-tutorial/overview/) or [Vue (community)](/developing/vue-tutorial/overview/)). diff --git a/src/pages/developing/frameworks/react.mdx b/src/pages/developing/frameworks/react.mdx index fca981364f6..c7ffcf8f038 100755 --- a/src/pages/developing/frameworks/react.mdx +++ b/src/pages/developing/frameworks/react.mdx @@ -80,7 +80,7 @@ Design System. Components require the use of a build pipeline in your project. This could be in the form of a bundler, framework, or other build tool. Some examples include -NextJS, Vite, Parcel, and Webpack. A comprehensive list is available in the +Next.js, Vite, Parcel, and Webpack. A comprehensive list is available in the [react documentation](https://react.dev/learn/start-a-new-react-project). To use a component, you can import it directly from the package: @@ -122,7 +122,7 @@ A full list of available icons is provided in the [icon library](/guidelines/icons/library/). For a more in depth introduction to using `@carbon/react` in a webpack-based -app, [check out our react tutorial](/developing/react-tutorial/overview/). +app, [check out our React tutorial](/developing/react-tutorial/overview/). ## Development diff --git a/src/pages/developing/get-started.mdx b/src/pages/developing/get-started.mdx index 49d4419b952..1650acf830d 100644 --- a/src/pages/developing/get-started.mdx +++ b/src/pages/developing/get-started.mdx @@ -41,14 +41,15 @@ as well as our GitHub repos and Storybooks for your framework of choice. ### Take a tutorial -We offer tutorials in Angular, React, and Vue to guide you in creating an app -with the Carbon Design System. We’ll teach you the ins and outs of using Carbon -components, and introduce web development best practices along the way. +We offer tutorials in Angular, React using Next.js, and Vue to guide you in +creating an app with the Carbon Design System. We’ll teach you the ins and outs +of using Carbon components, and introduce web development best practices along +the way. diff --git a/src/pages/developing/react-tutorial/faq.mdx b/src/pages/developing/react-tutorial/faq.mdx index 2db1ce72f1e..232cc51d7e7 100644 --- a/src/pages/developing/react-tutorial/faq.mdx +++ b/src/pages/developing/react-tutorial/faq.mdx @@ -1,8 +1,8 @@ --- title: FAQs description: - Welcome to Carbon! This tutorial will guide you in creating a React app with - the Carbon Design System. + Welcome to Carbon! This tutorial will guide you in creating a React app using + Next.js with the Carbon Design System. tabs: [ 'Overview', @@ -16,23 +16,6 @@ tabs: ] --- -### I am getting an error that says `failed to find manifest for cf`. What do I do? - -- The 5th step assumes your spaces are in the US South region. To successfully - deploy, you might need to update the region code (e.g. - `api.[REGION].cf.cloud.ibm.com`) to the region where your spaces were created, - or create a space in the US South region. - -- If you don't have an org, create one - [here](https://cloud.ibm.com/account/cloud-foundry). - - In the top nav go to Manage > Account > Account resources > Cloud Foundry - orgs - - The name you give it doesn't matter, just take note of the region you - select, and use that region's API endpoint (e.g. - `api.[REGION].cf.cloud.ibm.com`) - - Find regions and endpoints - [here](https://cloud.ibm.com/docs/cloud-foundry-public?topic=cloud-foundry-public-endpoints). - ### I am getting an error that says `yarn lockfile missing`. How do I fix this? - This error can occur when the `yarn.lock` file is either missing or differs @@ -48,16 +31,6 @@ tabs: and push up any changes. If this still does not work, ensure your `yarn.lock` file matches the one at the start of the tutorial step -### When will my PR be reviewed? - -- If your PR is passing, it will automatically get approved and closed by a bot. - After it's closed, you can move on to the next step. - -- If your PR is failing, try out the troubleshooting tips on this page first to - fix it. If it's still failing, reach out for help in our slack channel - `#carbon-react` or tag `@carbon-design-system/developers` in a comment on your - PR for help. - ### How can I show others my completion status? - Proof of your completion of the tutorial can be seen by filtering the PR list @@ -67,12 +40,8 @@ tabs: your username. Replace `YOURUSERNAMEHERE` with your username in the following link: - - https://github.com/carbon-design-system/carbon-tutorial/pulls?q=author%3AYOURUSERNAMEHERE - -### Other troubleshooting tips + - https://github.com/carbon-design-system/carbon-tutorial-nextjs/pulls?q=author%3AYOURUSERNAMEHERE -- We updated the `react-scripts` dependency to `v5.0.1`. Pull from `upstream` - and run `yarn` or `npm install` to update your remote branch. -- You no longer need the `.env` with the updated `react-scripts` dependency. If - you are up to date, you can delete that file (previously at the root level). -- Run `yarn format` and commit any changes made. +- It can also be demonstrated by deploying your app. Please see further + documentation + [here](/developing/react-tutorial/step-5#build-for-production-and-deploy). diff --git a/src/pages/developing/react-tutorial/images/carbon-badge.png b/src/pages/developing/react-tutorial/images/carbon-badge.png deleted file mode 100644 index 91b47daf235..00000000000 Binary files a/src/pages/developing/react-tutorial/images/carbon-badge.png and /dev/null differ diff --git a/src/pages/developing/react-tutorial/overview.mdx b/src/pages/developing/react-tutorial/overview.mdx index 95386037c65..44663b969bd 100644 --- a/src/pages/developing/react-tutorial/overview.mdx +++ b/src/pages/developing/react-tutorial/overview.mdx @@ -1,8 +1,8 @@ --- title: Tutorial overview description: - Welcome to Carbon! This tutorial will guide you in creating a React app with - the Carbon Design System. + Welcome to Carbon! This tutorial will guide you in creating a React app using + Next.js with the Carbon Design System. tabs: [ 'Overview', @@ -20,9 +20,10 @@ import Preview from 'components/Preview'; -Welcome to Carbon! This tutorial will guide you in creating a React app with the -Carbon Design System. We'll teach you the ins and outs of using Carbon -components, while introducing web development best practices along the way. +Welcome to Carbon! This tutorial will guide you in creating a React app using +Next.js with the Carbon Design System. We'll teach you the ins and outs of using +Carbon components, while introducing web development best practices along the +way. @@ -34,13 +35,13 @@ components, while introducing web development best practices along the way. -Here's a [preview](https://v11-react-step-5--carbon-tutorial.netlify.app) of -what you will build: +Here's a [preview](https://carbon-tutorial-nextjs.vercel.app/) of what you will +build: -Starting with Create React App, let's install Carbon and begin using Carbon -components. By the end you will have a React app that uses the UI Shell to -navigate between pages. +Starting from a base Create Next App, let's install Carbon and begin using +Carbon components. By the end you will have a Next.js app that uses the UI Shell +to navigate between pages. @@ -41,13 +41,14 @@ navigate between pages. ## Preview -A [preview](https://v11-react-step-2--carbon-tutorial.netlify.app) of what you -will build: +A +[preview](https://carbon-tutorial-nextjs-nrt4ljsgl-carbon-design-system.vercel.app/) +of what you will build: Hello Carbon! Well, not quite yet. This is the starting point for the Carbon - tutorial. + React tutorial. ``` with: -```jsx path=src/App.js +```jsx path=src/app/page.js ``` @@ -231,34 +251,24 @@ the following files inside `src/components/TutorialHeader`: ```bash src/components/TutorialHeader β”œβ”€β”€_tutorial-header.scss -β”œβ”€β”€index.js └──TutorialHeader.js ``` ### Add UI Shell Sass -Next, in `app.scss`, we'll import our `TutorialHeader` styles. Your file should -now look like this: +Next, in `globals.scss`, we'll import our `TutorialHeader` styles. Add this line +to the top of the file: -```scss path=src/app.scss -@use './components/TutorialHeader/tutorial-header'; +```scss path=src/app/globals.scss +@use '@/components/TutorialHeader/tutorial-header'; ``` ### Import and export the header -In `src/components/TutorialHeader/index.js`, import and export our -`TutorialHeader` component like so: - -```javascript path=src/components/TutorialHeader/index.js -import TutorialHeader from './TutorialHeader'; -export default TutorialHeader; -``` - Next we'll import our Carbon UI Shell components into `TutorialHeader.js`. Set up the file like so: ```javascript path=src/components/TutorialHeader/TutorialHeader.js -import React from 'react'; import { Header, HeaderContainer, @@ -329,11 +339,17 @@ straight to the main content. ### Import icons +First we will install the icons we will use in the header + +```bash +yarn add @carbon/icons-react +``` + Now let's import the icons. In the `TutorialHeader.js` file, we need to import each individual icon we will use. ```javascript path=src/components/TutorialHeader/TutorialHeader.js -import { Switcher, Notification, UserAvatar } from '@carbon/react/icons'; +import { Switcher, Notification, UserAvatar } from '@carbon/icons-react'; ``` Then we need to add the `HeaderGlobalAction` component inside of the @@ -363,30 +379,53 @@ With: ### Render the header Next we'll render our UI Shell by importing our `TutorialHeader` component and -`Content` into `App.js`. Your imports should look like this: - -```javascript path=src/App.js -import React, { Component } from 'react'; -import './app.scss'; -import { Button, Content } from '@carbon/react'; -import TutorialHeader from './components/TutorialHeader'; -``` - -Our `return` currently just contains a `Button`. Let's update that to include -our imported components. This should look like the following: - -```javascript path=src/App.js -class App extends Component { - render() { - return ( - <> - - - - - - ); - } +`Content` into a provider components in the Root Layout. We do this because +layout components in Next.js 13 are server-side components. + + + +**Note:** We can wrap the `{children}` in Root Layout with a Provider component +that will use to hold the components we want across all pages. See this +[explanation](https://nextjs.org/docs/getting-started/react-essentials#rendering-third-party-context-providers-in-server-components) +in Next docs. + + + +```javascript path=src/app/layout.js +import './globals.scss'; +import { Providers } from './providers'; + +export const metadata = { + title: 'Carbon + Next13', + description: 'IBM Carbon Tutorial with Next.js 13', +}; + +export default function RootLayout({ children }) { + return ( + + + {children} + + + ); +} +``` + +Create a `providers.js` file within the app folder with the following content. + +```javascript path=src/app/providers.js +'use client'; + +import TutorialHeader from '@/components/TutorialHeader/TutorialHeader'; +import { Content } from '@carbon/react'; + +export function Providers({ children }) { + return ( +
+ + {children} +
+ ); } ``` @@ -394,200 +433,135 @@ You should now see a styled UI Shell header and a button below it. ## Create pages -Next thing we need to do is create the files for our content. Start by creating -a folder called `content` in `src`. This should be a sibling of -`src/components`. +Next thing we need to do is create the files for our content. We already have a +folder called `app` in `src`. This should be a sibling of `src/components`. -Since our app will have two pages, we'll create two folders in `src/content`. +Since our app will have two pages, we'll create two folders in `src/app`. ```bash -src/content -β”œβ”€β”€ LandingPage -└── RepoPage +src/app +β”œβ”€β”€ home +└── repos ``` -Next, we'll set up these folders the same way we set up -`src/components/TutorialHeader`. +Next.js uses these folders for page routing which is built into the framework, +we do not need separate React routing. In each there is a `page.js` and +optionally a `layout.js` and styling sheet. -Create the following files in the `LandingPage` folder: +Create the following files in the `home` folder: ```bash -src/content/LandingPage +src/app/home β”œβ”€β”€ _landing-page.scss -β”œβ”€β”€ index.js -└── LandingPage.js +└── page.js ``` -Create the following files in the `RepoPage` folder: +Create the following files in the `repos` folder: ```bash -src/content/RepoPage +src/app/repos β”œβ”€β”€ _repo-page.scss -β”œβ”€β”€ index.js -└── RepoPage.js +└── page.js ``` ### Set up content Sass -Next, we'll import our content Sass files in `app.scss`, like so: +Next, we'll import our content Sass files in `globals.scss`, like so: -```scss path=src/app.scss -@use './components/TutorialHeader/tutorial-header'; -@use './content/LandingPage/landing-page'; -@use './content/RepoPage/repo-page'; +```scss path=src/app/globals.scss +@use '@/app/home/landing-page'; +@use '@/app/repos/repo-page'; ``` ### Import and export content pages Now that our stylesheets are set up, we need to create our pages' components. Starting with `LandingPage`, just like with our header, we need to export the -component in `src/content/LandingPage/index.js` by adding: +component in `javascript path=src/app/home/page.js` by adding: -```javascript path=src/content/LandingPage/index.js -import LandingPage from './LandingPage'; -export default LandingPage; -``` - -Next in `LandingPage.js`, we'll create our component. - -```javascript path=src/content/LandingPage/LandingPage.js -import React from 'react'; +```javascript path=src/app/home/page.js +`use client`; -const LandingPage = () => { +export default function LandingPage() { return
LANDING PAGE
; -}; - -export default LandingPage; +} ``` -We'll repeat this process with `RepoPage`. +And we will add this into our root page: -In `src/content/RepoPage/index.js`, import and export the `RepoPage` component -like so: +```javascript path=src/app/page.js +import LandingPage from './home/page'; -```javascript path=src/content/RepoPage/index.js -import RepoPage from './RepoPage'; -export default RepoPage; +export default function Page() { + return ; +} ``` -Then in `RepoPage.js` create the component. +We'll repeat this process with `RepoPage`. -```javascript path=src/content/RepoPage/RepoPage.js -import React from 'react'; +```javascript path=src/app/repos/page.js +`use client`; -const RepoPage = () => { +export default function RepoPage() { return
REPO PAGE
; -}; - -export default RepoPage; -``` - -Awesome! We've just created our content pages. Next thing we need to do is -render them with our router. - -## Add routing - -We've updated our app to render our header, but now we need to add routing -functionality. To do this we need to install `react-router-dom`. Go ahead and -stop your development server (with `CTRL-C`) and then: - -```bash -yarn add react-router-dom@5.0.0 -yarn start -``` - -First, we need to wrap our app in the `Router` component. In the root -`index.js`, add the import: - -```javascript path=src/index.js -import { HashRouter as Router } from 'react-router-dom'; -``` - - - -**Note:** We're using `HashRouter` instead of `BrowserRouter` to simplify -deployments in upcoming tutorial steps. Learn more about the React Router -[here](https://reacttraining.com/react-router/web/api/BrowserRouter). - - - -Then, update the `render()` function to include the `Router`. - -```javascript path=src/index.js -createRoot(document.getElementById('root')).render( - - - -); +} ``` -In order to render our content pages, we need to add the following imports in -`App.js` below our existing imports. +Navigate to the repos page by adding `/repos` at the end of your locally hosted +site to see your repos page. -```javascript path=src/App.js -import { Route, Switch, BrowserRouter } from 'react-router-dom'; -import { Content } from '@carbon/react'; -import LandingPage from './content/LandingPage'; -import RepoPage from './content/RepoPage'; -``` +Awesome! We've just created our content pages with automatic page routing +courtesy of Next.js. -This allows us to use our page content components and routing components from -`react-router-dom`. +After that we need to do a couple of quick fixes to the UI Shell to work with +Next.js links. -The next thing we need to do is update what we're returning to `App.js`. We -currently just have a div with some dummy content. In order to render our pages -correctly, we need to replace the `div` with `` (and remove the -text inside). - -Now inside `App.js` we'll add the following: +Add the `Link` import in `TutorialHeader.js`: -```jsx path=src/App.js - - - - - - - - +```javascript path=src/components/TutorialHeader/TutorialHeader.js +import Link from 'next/link'; ``` -After that we need to do a couple quick fixes to the UI Shell to have it work -with the React router. - -Add the `Link` import in `TutorialHeader.js`: +We need to use the `Link` component instead of the default anchor elements to +prevent full page reload when navigating to different pages in Next.js +applications. To use `Link`, we wrap `HeaderName` component and pass through +`href` elements to it: ```javascript path=src/components/TutorialHeader/TutorialHeader.js -import { Link } from 'react-router-dom'; + + Carbon Tutorial + ``` -We need to use the `Link` component instead of the default anchor elements to -prevent full page reload when navigating to different pages with React Router. -To use `Link`, update the `HeaderName` component to use the `element` prop and -replace the `href` with `to`: +Do the same with the components `HeaderNavigation` and `HeaderSideNavItems` that +contain `href="/repos"`, updating them to: ```javascript path=src/components/TutorialHeader/TutorialHeader.js - - Carbon Tutorial - + + + Repositories + + ``` -Do the same with the components that contain `href="/repos"`, updating them to: +and the following: ```javascript path=src/components/TutorialHeader/TutorialHeader.js - - Repositories - + + + Repositories + + ``` You should now have a working header that routes to different pages without full page reload! However, our page does not match the design specs. We need to change the header theme to `g100` to match the specs. -In `App.js` we will add inline theming for our navigation. First, we need to -import our new `Theme` component. +In `providers.js` we will add inline theming for our navigation. First, we need +to import our new `Theme` component. -```javascript path=src/App.js +```javascript path=src/app/providers.js import { Content, Theme } from '@carbon/react'; ``` @@ -595,29 +569,13 @@ Then, we will wrap `Theme` around our header, and set the zoned theme using the `theme` prop, which accepts one of four strings: `"white"`, `"g10"`, `"g90"` or `"g100"`. -```javascript path=src/App.js - +```javascript path=src/app/providers.js +
- - - - - - - -``` - -You might have noticed that the landing and repo page content disappeared. This -is because we now have a wrapper around the UI Shell, and the spacing is off. To -fix this, we'll add the following override in `index.scss` below our style -import: - -```scss path=src/index.scss -.cds--content { - margin-top: 3rem; -} + {children} +
``` We have one last thing to fix before we're done. Because we changed the header @@ -687,7 +645,7 @@ have `.yarn/cache` commit changes. Then, push to your repository: ```bash -git push origin v11-react-step-1 +git push origin v11-next-step-1 ``` @@ -707,7 +665,7 @@ over HTTPS. **Note:** If you receive a `non-fast-forward` error, it's likely that your forked repository is behind the original repository and needs to be updated. This can happen if the tutorial was updated after you began working on it. To -fix, run `git pull upstream v11-react-step-1` to merge the changes into your +fix, run `git pull upstream v11-next-step-1` to merge the changes into your branch, then you can try pushing again. Or, you can [manually merge](https://help.github.com/en/articles/syncing-a-fork) in the upstream changes. @@ -717,9 +675,9 @@ upstream changes. ### Pull request (PR) Finally, visit -[carbon-tutorial](https://github.com/carbon-design-system/carbon-tutorial) to -"Compare & pull request". In doing so, make sure that you are comparing to -`v11-react-step-1` into `base: v11-react-step-1`. Take notice of the +[carbon-react-tutorial](https://github.com/carbon-design-system/carbon-tutorial-nextjs) +to "Compare & pull request". In doing so, make sure that you are comparing to +`v11-next-step-1` into `base: v11-next-step-1`. Take notice of the [Netlify](https://www.netlify.com) bot that deploys a preview of your PR every time that you push new commits. These previews can be shared and viewed by anybody to assist the PR review process. diff --git a/src/pages/developing/react-tutorial/step-2.mdx b/src/pages/developing/react-tutorial/step-2.mdx index 9993d264a7e..cadac7e32d2 100644 --- a/src/pages/developing/react-tutorial/step-2.mdx +++ b/src/pages/developing/react-tutorial/step-2.mdx @@ -1,8 +1,8 @@ --- title: 2. Building pages description: - Welcome to Carbon! This tutorial will guide you in creating a React app with - the Carbon Design System. + Welcome to Carbon! This tutorial will guide you in creating a React app using + Next.js with the Carbon Design System. tabs: [ 'Overview', @@ -20,7 +20,7 @@ import Preview from 'components/Preview'; -Now that we have a React app using the UI Shell, it's time to build a few static +Now that we have our app using the UI Shell, it's time to build a few static pages. In this step, we'll become comfortable with the Carbon grid and various Carbon components. @@ -41,13 +41,14 @@ Carbon components. ## Preview -A [preview](https://v11-react-step-3--carbon-tutorial.netlify.app) of what -you'll build: +A +[preview](https://carbon-tutorial-nextjs-huv7un4ex-carbon-design-system.vercel.app/) +of what you'll build: @@ -93,41 +94,15 @@ yarn Then, start the app: ```bash -yarn start +yarn dev ``` You should see something similar to where the [previous step](/developing/react-tutorial/step-1) left off. -### IE11 polyfills - -Before we get started with this step, we'll be adding some components that -require IE11 polyfills. As shown in the -[Carbon React documentation](https://github.com/carbon-design-system/carbon/blob/v10/packages/react/.storybook/polyfills.js), -go ahead and add these imports to the top of the root `index.js`. They aren't -all needed, but we'll add them all to play it safe for the duration of the -tutorial. - -```javascript path=src/index.js -import 'core-js/modules/es7.array.includes'; -import 'core-js/modules/es6.array.fill'; -import 'core-js/modules/es6.string.includes'; -import 'core-js/modules/es6.string.trim'; -import 'core-js/modules/es7.object.values'; -``` - - - -**Note:** You may be wondering where `core-js`came from because it's not a -Carbon package and we haven't explicitly installed it. Run `yarn why core-js` -and you'll see there are a number of packages that have brought it in as a -dependency. - - - ## Add landing page grid -Let's add our grid elements to `LandingPage.js`. +Let's add our grid elements to our `LandingPage` page component. In order to use the grid, we need to wrap everything in a ``. Because we're building with the new CSS Grid, we won't be using typical rows. We'll use @@ -138,7 +113,7 @@ the `sm`, `md`, and `lg` props. For example, `` means the column will span 2/4 columns at the small breakpoint, 8/8 columns at the medium breakpoint, 8/16 columns at the large breakpoint. -We've included the designs for this tutorial app in the `design.sketch` file +We've included the designs for this tutorial app in the `design.figma` file found as a top-level file in the `carbon-tutorial` repository. But, if you don't have Sketch installed and available to inspect the design, we'll provide screenshots. @@ -153,9 +128,10 @@ screenshots. -First, we need to import our grid components at the top of `LandingPage.js`: +First, we need to import our grid components at the top of `LandingPage`: -```javascript path=src/content/LandingPage/LandingPage.js +```javascript path=src/app/home/page.js +'use client'; import { Grid, Column } from '@carbon/react'; ``` @@ -166,7 +142,7 @@ background looks like it has four columns of equal width. We'll make rows like so: -```jsx path=src/content/LandingPage/LandingPage.js +```jsx path=src/app/home/page.js return ( @@ -218,13 +194,13 @@ components we need. Because we'll be importing several components for this page, we'll import them directly from the `@carbon/react` package instead of the direct path for each one. -```javascript path=src/content/LandingPage/LandingPage.js +```javascript path=src/app/home/page.js import { Breadcrumb, BreadcrumbItem, Grid, Column } from '@carbon/react'; ``` We can now add our component to the first row, along with a header, like so: -```jsx path=src/content/LandingPage/LandingPage.js +```jsx path=src/app/home/page.js @@ -242,7 +218,7 @@ You may notice that the styles look off. Don't worry, we'll fix these later. In our second row we'll need `Tabs` and `Button` components. We'll update the `@carbon/react` import to: -```javascript path=src/content/LandingPage/LandingPage.js +```javascript path=src/app/home/page.js import { Breadcrumb, BreadcrumbItem, @@ -269,7 +245,7 @@ supported. -```jsx path=src/content/LandingPage/LandingPage.js +```jsx path=src/app/home/page.js @@ -341,10 +317,10 @@ Same goes for the `TabList` opening tag: ``` Next, we'll need to add some styling overrides to move the tabs to the right on -large viewports. Create a file `_overrides.scss` in `src/content/LandingPage` -with this declaration block. +large viewports. Create a file `_overrides.scss` in `src/app/home` with this +declaration block. -```scss path=src/content/LandingPage/_overrides.scss +```scss path=src/app/home/_overrides.scss .landing-page__r2 .cds--tabs--scrollable { transform: translateZ(0); justify-content: flex-end; @@ -367,7 +343,7 @@ with this declaration block. Then in `_landing-page.scss` add this import at the top of the file. -```scss path=src/content/LandingPage/_landing-page.scss +```scss path=src/app/home/_landing-page.scss @use './overrides.scss'; ``` @@ -381,21 +357,28 @@ names, you have a consolidated list of styling declaration blocks to review. We can now add our images and text for each column in the first `Tab` in -`LandingPage.js`. +`LandingPage`. + +Let's import `Image` from Next.js by adding the following import under our +Carbon React component imports. + +```jsx path=src/app/home/page.js +import Image from 'next/image'; -```jsx path=src/content/LandingPage/LandingPage.js - Carbon illustration - +; ``` Now let's set the image size in `_landing-page.scss`: -```scss path=src/content/LandingPage/_landing-page.scss +```scss path=src/app/home/_landing-page.scss .landing-page__illo { max-width: 100%; } @@ -410,7 +393,7 @@ we'll leave the code as is. The third row will be created in a later tutorial, so we'll just add the headers for now. -```jsx path=src/content/LandingPage/LandingPage.js +```jsx path=src/app/home/page.js @@ -438,7 +421,7 @@ In `_landing-page.scss`, add these imports at the **top** of the file (above our overrides import) so we can use Carbon breakpoints, tokens, and typography Sass mixins and functions: -```scss path=src/content/LandingPage/_landing-page.scss +```scss path=src/app/home/_landing-page.scss @use '@carbon/react/scss/spacing' as *; @use '@carbon/react/scss/type' as *; @use '@carbon/react/scss/breakpoint' as *; @@ -466,7 +449,7 @@ mixins and functions: Back to `_landing-page.scss`, we need to add space above the breadcrumb and below the heading. For that, add: -```scss path=src/content/LandingPage/_landing-page.scss +```scss path=src/app/home/_landing-page.scss .landing-page__banner { padding-top: $spacing-05; padding-bottom: $spacing-07 * 4; @@ -486,7 +469,7 @@ Looking at the design, we need a wall-to-wall light gray background behind the banner and also behind the third row. This is a great opportunity to use a Sass mixin. We could put this at the top of `_landing-page.scss`, but it's best practice to place mixins in a dedicated file, so create a `_mixins.scss` file in -`src/content/LandingPage`. +`src/app/home`. Add the following in `_mixins.scss`. Per the design we need to use Gray 10 for our banner background color, which can be set with the `$layer-01` @@ -495,7 +478,7 @@ we want the background to extend into the grid's outermost gutters to go the full width of the viewport, so given the DOM structure, we can achieve that by setting the background in an absolutely positioned pseudo element. -```scss path=src/content/LandingPage/_mixins.scss +```scss path=src/app/home/_mixins.scss @use '@carbon/react/scss/spacing' as *; @use '@carbon/react/scss/theme' as *; @@ -508,7 +491,7 @@ setting the background in an absolutely positioned pseudo element. After you have created `_mixins.scss`, import it at the **top** of `_landing-page.scss`. By now you should have six imports: -```scss path=src/content/LandingPage/_landing-page.scss +```scss path=src/app/home/_landing-page.scss @use '@carbon/react/scss/spacing' as *; @use '@carbon/react/scss/type' as *; @use '@carbon/react/scss/breakpoint' as *; @@ -520,7 +503,7 @@ After you have created `_mixins.scss`, import it at the **top** of Now to use the new mixin, update the `.landing-page__banner` declaration block to: -```scss path=src/content/LandingPage/_landing-page.scss +```scss path=src/app/home/_landing-page.scss .landing-page__banner { padding-top: $spacing-05; padding-bottom: $spacing-07 * 4; @@ -546,7 +529,7 @@ translate design to development. So, looking up the [type token](https://www.carbondesignsystem.com/guidelines/typography/productive), we know to use `productive-heading-05`: -```scss path=src/content/LandingPage/_landing-page.scss +```scss path=src/app/home/_landing-page.scss .landing-page__heading { @include type-style('productive-heading-05'); } @@ -559,7 +542,7 @@ design. By inspecting the tabs component, you can see that the tab height computes to `40px`. We can use that to create our negative top margin in rem units. -```scss path=src/content/LandingPage/_landing-page.scss +```scss path=src/app/home/_landing-page.scss .landing-page__r2 { margin-top: rem(-40px); } @@ -588,7 +571,7 @@ baseline, for consistency as well as development ease so `margins` and -```scss path=src/content/LandingPage/_landing-page.scss +```scss path=src/app/home/_landing-page.scss .tabs-group-content { padding: $spacing-10 $spacing-06; } @@ -630,7 +613,7 @@ Let's also add some styles for the last row, even though that will get used later in the tutorial. You'll notice that we get to re-use the `landing-page-background` mixin that we just created. -```scss path=src/content/LandingPage/_landing-page.scss +```scss path=src/app/home/_landing-page.scss .landing-page__r3 { padding-top: $spacing-09; padding-bottom: $spacing-09; @@ -646,7 +629,7 @@ later in the tutorial. You'll notice that we get to re-use the Lastly, we'll fix some grid alignment issues. We'll use one of our breakpoint mixins for the media queries, like so: -```scss path=src/content/LandingPage/_landing-page.scss +```scss path=src/app/home/_landing-page.scss .landing-page__banner, .landing-page__r2, .landing-page__r3 { @@ -661,12 +644,12 @@ mixins for the media queries, like so: ``` We are almost done with the landing page. You may notice a few styles are off. -To fix this, we'll update some of the overriding styles in `index.scss`. We +To fix this, we'll update some of the overriding styles in `globals.scss`. We already have some overriding styles for `.cds--content`. We need to add `padding: 0;` to this selector and add one more selector for the grid below that: -```scss path=src/index.scss +```scss path=src/app/globals.scss .cds--content { margin-top: 3rem; padding: 0; @@ -682,10 +665,10 @@ that: } ``` -Since we are using out `breakpoint` mixin, we need to import the styles for that +Since we are using our `breakpoint` mixin, we need to import the styles for that below our Carbon styles import: -```scss path=src/index.scss +```scss path=src/app/globals.scss @use '@carbon/react'; @use '@carbon/react/scss/breakpoint' as *; ``` @@ -695,18 +678,20 @@ page. ## Add repo page grid -Now in our `RepoPage.js` we'll import our `Grid` components at the top: +Now in our `RepoPage`component in the `src/app/repos/page.js` file we'll import +our `Grid` components at the top: -```javascript path=src/content/RepoPage/RepoPage.js +```javascript path=src/app/repos/page.js +'use client'; import { Grid, Column } from '@carbon/react'; ``` Then add our grid containers in the `return` section. -```javascript path=src/content/RepoPage/RepoPage.js +```javascript path=src/app/repos/page.js return ( - + Data table will go here @@ -715,17 +700,17 @@ return ( ## Build repo page -We currently have `RepoPage.js` that just contains a grid and placeholder -content for the time being. In the next tutorial step we're going to be querying -an API to populate the `DataTable` component in this page. As a best practice to +We currently have `RepoPage` that just contains a grid and placeholder content +for the time being. In the next tutorial step we're going to be querying an API +to populate the `DataTable` component in this page. As a best practice to separate data fetching from the presentation components, go ahead and create a -`RepoTable.js` as a sibling to `RepoPage.js` in `src/content/RepoPage`. +`RepoTable.js` as a sibling to `page.js` in `src/app/repos`. ### Build data table First, we'll add our data table by importing a few components in `RepoTable.js`: -```javascript path=src/content/RepoPage/RepoTable.js +```javascript path=src/app/repos/RepoTable.js import React from 'react'; import { DataTable, @@ -745,7 +730,7 @@ import { Then, let's create the `RepoTable` component and export it at the very bottom of `RepoTable.js`. -```javascript path=src/content/RepoPage/RepoTable.js +```javascript path=src/app/repos/RepoTable.js const RepoTable = ({ rows, headers }) => { return ( { {headers.map((header) => ( - + {header.header} ))} @@ -814,15 +799,15 @@ into the component. -At this point, return to `RepoPage.js` because now we need to render a static +At this point, return to `RepoPage` because now we need to render a static `RepoTable`. ### Render data table -Import `RepoTable` in `RepoPage.js`. +Import `RepoTable` into `RepoPage`. -```javascript path=src/content/RepoPage/RepoPage.js -import React from 'react'; +```javascript path=src/app/repos/page.js +'use client'; import RepoTable from './RepoTable'; import { Grid, Column } from '@carbon/react'; ``` @@ -831,7 +816,7 @@ Then below the imports, include the following arrays to pass into the `RepoTable` component. We'll be setting the `rows` array from an API in the next tutorial step, but for now, static example rows will suffice. -```javascript path=src/content/RepoPage/RepoPage.js +```javascript path=src/app/repos/page.js const headers = [ { key: 'name', @@ -890,10 +875,9 @@ const rows = [ ]; ``` -Lastly in `RepoPage.js`, we need to simply replace `Data table will go here` -with: +Lastly in `RepoPage`, we need to simply replace `Data table will go here` with: -```jsx path=src/content/RepoPage/RepoPage.js +```jsx path=src/app/repos/page.js ``` @@ -904,7 +888,7 @@ vertical spacing issues. In `_repo-page.scss`, add the following styles: -```scss path=src/content/RepoPage/_repo-page.scss +```scss path=src/app/repos/_repo-page.scss @use '@carbon/react/scss/spacing' as *; .repo-page__r1 { @@ -929,9 +913,10 @@ yarn ci-check -**Note:** Having issues running the CI check? -[Step 1]() -has troubleshooting notes that may help. +**Note:** If the `ci-check` is giving an error, it's likely that some of your +source files are not properly formatted. This could happen if your text editor +isn't formatting with Prettier on save. To get `ci-check` to pass, run +`yarn format` then re-run `yarn ci-check`. @@ -948,7 +933,7 @@ git add --all && git commit -m "feat(tutorial): complete step 2" Then, push to your repository: ```bash -git push origin v11-react-step-2 +git push origin v11-next-step-2 ``` @@ -962,9 +947,9 @@ troubleshooting notes that may help. ### Pull request (PR) Finally, visit -[carbon-tutorial](https://github.com/carbon-design-system/carbon-tutorial) to -"Compare & pull request". In doing so, make sure that you are comparing to -`v11-react-step-2` into `base: v11-react-step-2`. +[carbon-react-tutorial](https://github.com/carbon-design-system/carbon-tutorial) +to "Compare & pull request". In doing so, make sure that you are comparing to +`v11-next-step-2` into `base: v11-next-step-2`. diff --git a/src/pages/developing/react-tutorial/step-3.mdx b/src/pages/developing/react-tutorial/step-3.mdx index 997c82b33a9..4dcfc1ed852 100644 --- a/src/pages/developing/react-tutorial/step-3.mdx +++ b/src/pages/developing/react-tutorial/step-3.mdx @@ -1,8 +1,8 @@ --- title: 3. Using APIs description: - Welcome to Carbon! This tutorial will guide you in creating a React app with - the Carbon Design System. + Welcome to Carbon! This tutorial will guide you in creating a React app using + Next.js with the Carbon Design System. tabs: [ 'Overview', @@ -48,13 +48,14 @@ To do so, we'll be using [Octokit Core](https://github.com/octokit/core.js/#readme), a client that makes it easy to interact with Github's APIs. -A [preview](https://v11-react-step-4--carbon-tutorial.netlify.app) of what you -will build (see repositories page): +A +[preview](https://carbon-tutorial-nextjs-8xoxdcixk-carbon-design-system.vercel.app/) +of what you will build (see repositories page): { +```javascript path=src/app/repos/page.js +function RepoPage() { useEffect(() => { async function getCarbonRepos() { const res = await octokitClient.request('GET /orgs/{org}/repos', { @@ -173,11 +175,10 @@ const RepoPage = () => { getCarbonRepos(); }, []); -... ``` -At this point, if you navigate to the `Repositories` page in your running app -and view your browser's console (e.g. +At this point, if you navigate to the Repositories page `/repos` in your running +app and view your browser's console (e.g. [Chrome DevTools](https://developer.chrome.com/docs/devtools/)), you should see the response from GitHub! @@ -186,17 +187,18 @@ the response from GitHub! Our last column in the data table will be a comma-separated list of repository and home page links, so let's create a component called `LinkList`. -Import `Link` at the top of `RepoPage.js`. The imports should look like this. +Import `Link` at the top of `/app/repos/page.js`. The imports should look like +this. -```javascript path=src/content/RepoPage/RepoPage.js +```javascript path=src/app/repos/page.js import { Link, Grid, Column } from '@carbon/react'; ``` -Then use `Link` in this component that has two props (`url` and `homepageUrl`) +Then use `Link` in this component. It has two props (`url` and `homepageUrl`) and returns an unordered list. If the repository does not have a home page URL, only render the repository link. -```javascript path=src/content/RepoPage/RepoPage.js +```javascript path=src/app/repos/page.js const LinkList = ({ url, homepageUrl }) => (
  • @@ -216,7 +218,7 @@ As a final helper, let's create a function that transforms row data to our expected header keys. Notice how we're using our new `LinkList` component to generate the value of the `links` key in each row. -```javascript path=src/content/RepoPage/RepoPage.js +```javascript path=src/app/repos/page.js const getRowItems = (rows) => rows.map((row) => ({ ...row, @@ -234,7 +236,7 @@ const getRowItems = (rows) => Now that we have our data, let's dispose of our dummy `rows` and populate the data table with real data. -First, towards the top of `RepoPage.js` delete the `rows` array because we no +First, towards the top of `RepoPage` delete the `rows` array because we no longer need the example rows. Next, let's add a couple variables that will help us store useful information @@ -246,18 +248,17 @@ manage our state. Import React's [useState](https://reactjs.org/docs/hooks-state.html) by modifying the `React` import. -```javascript path=src/content/RepoPage/RepoPage.js +```javascript path=src/app/repos/page.js import React, { useEffect, useState } from 'react'; ``` Then, inside the `RepoPage` component: -```javascript path=src/content/RepoPage/RepoPage.js -const RepoPage = () => { +```javascript path=src/app/repos/page.js +function RepoPage() { const [loading, setLoading] = useState(true); const [error, setError] = useState(); const [rows, setRows] = useState([]); -... ``` Now, instead of using `console.log` to log the github data response, let's treat @@ -265,35 +266,33 @@ the response data by passing it through our `getRowItems` helper and saving the result in our new `rows` variable. Replace the `console.log(res.data);` line inside `if (res.status === 200)` with: -```javascript path=src/content/RepoPage/RepoPage.js +```javascript path=src/app/repos/page.js setRows(getRowItems(res.data)); ``` Let's also replace our error log line inside the `else` statement with: -```javascript path=src/content/RepoPage/RepoPage.js +```javascript path=src/app/repos/page.js setError('Error obtaining repository data'); ``` To complete our `getCarbonRepos` function, let's set the loading state to false right after the `else` statement: -```javascript path=src/content/RepoPage/RepoPage.js -... - if (res.status === 200) { - setRows(getRowItems(res.data)); - } else { - setError('Error obtaining repository data'); - } - setLoading(false); -... +```javascript path=src/app/repos/page.js +if (res.status === 200) { + setRows(getRowItems(res.data)); +} else { + setError('Error obtaining repository data'); +} +setLoading(false); ``` Finally, let's modify our component's `return()` statement to display different information depending on the states of our request: loading, error or complete. Replace the current return statement with: -```javascript path=src/content/RepoPage/RepoPage.js +```javascript path=src/app/repos/page.js if (loading) { return 'Loading...'; } @@ -341,7 +340,7 @@ to a column. To do so, in `RepoTable.js`, add this look-up function as the first lines inside the `RepoTable`. This should go immediately before the component's `return()`. -```javascript path=src/content/RepoPage/RepoTable.js +```javascript path=src/app/repos/RepoTable.js const getRowDescription = (rowId) => { const row = rows.find(({ id }) => id === rowId); return row ? row.description : ''; @@ -350,7 +349,7 @@ const getRowDescription = (rowId) => { Finally, in `RepoTable.js`, replace `

    Row description

    ` with: -```html path=src/content/RepoPage/RepoTable.js +```html path=src/app/repos/RepoTable.js

    {getRowDescription(row.id)}

    ``` @@ -362,16 +361,16 @@ component. We could stop here, but there's more to be done! Let's replace the `Loading...` string with the [DataTableSkeleton component](https://react.carbondesignsystem.com/?path=/story/components-datatable--skeleton). -To do so, back to `RepoPage.js`, add the `DataTableSkeleton` import by modifying +To do so, back to `RepoPage`, add the `DataTableSkeleton` import by modifying the existing `@carbon/react` import. -```javascript path=src/content/RepoPage/RepoPage.js +```javascript path=src/app/repos/page.js import { Link, DataTableSkeleton, Grid, Column } from '@carbon/react'; ``` Then replace the `if (loading) return 'Loading...';` with: -```javascript path=src/content/RepoPage/RepoPage.js +```javascript path=src/app/repos/page.js if (loading) { return ( @@ -401,8 +400,8 @@ data, and then paginate the in-memory row data. Initialize the new state variables that we'll use for pagination as the first lines inside the `RepoPage`. -```javascript path=src/content/RepoPage/RepoPage.js -const RepoPage = () => { +```javascript path=src/app/repos/page.js +function RepoPage() { const [firstRowIndex, setFirstRowIndex] = useState(0); const [currentPageSize, setCurrentPageSize] = useState(10); ... @@ -415,7 +414,7 @@ Then we need to update our `RepoTable` `rows` prop to only render the subset of rows for the current "page". Update `` to: -```javascript path=src/content/RepoPage/RepoPage.js +```javascript path=src/app/repos/page.js `), add the `Pagination` component using the state variables that we previously initialized. -```javascript path=src/content/RepoPage/RepoPage.js +```javascript path=src/app/repos/page.js @@ -534,9 +533,9 @@ troubleshooting notes that may help. ### Pull request (PR) Finally, visit -[carbon-tutorial](https://github.com/carbon-design-system/carbon-tutorial) to -"Compare & pull request". In doing so, make sure that you are comparing to -`v11-react-step-3` into `base: v11-react-step-3`. +[carbon-tutorial-nextjs](https://github.com/carbon-design-system/carbon-tutorial-nextjs) +to "Compare & pull request". In doing so, make sure that you are comparing to +`v11-next-step-3` into `base: v11-next-step-3`. diff --git a/src/pages/developing/react-tutorial/step-4.mdx b/src/pages/developing/react-tutorial/step-4.mdx index 36e2fc15db1..dc1c1039945 100644 --- a/src/pages/developing/react-tutorial/step-4.mdx +++ b/src/pages/developing/react-tutorial/step-4.mdx @@ -1,8 +1,8 @@ --- title: 4. Creating components description: - Welcome to Carbon! This tutorial will guide you in creating a React app with - the Carbon Design System. + Welcome to Carbon! This tutorial will guide you in creating a React app using + Next.js with the Carbon Design System. tabs: [ 'Overview', @@ -21,8 +21,8 @@ import Preview from 'components/Preview'; With two pages comprised entirely of Carbon components, let's revisit the -landing page and build a couple components of our own by using Carbon icons and -tokens. +landing page and build a couple components of our own by using Carbon pictograms +and tokens. @@ -49,13 +49,14 @@ Next, we're going to use Carbon assets to build application-specific components. We'll do so by including accessibility and responsive considerations all throughout. -A [preview](https://v11-react-step-5--carbon-tutorial.netlify.app) of what -you'll build (see bottom of page): +A +[preview](https://carbon-tutorial-nextjs-9hg9rmepp-carbon-design-system.vercel.app/) +of what you'll build (see bottom of page): @@ -100,7 +101,7 @@ yarn Then, start the app: ```bash -yarn start +yarn dev ``` You should see something similar to where the @@ -130,43 +131,34 @@ components. Create these files: ```bash src/components/Info β”œβ”€β”€_info.scss -β”œβ”€β”€index.js └──Info.js ``` Import `_info.scss` in `app.scss` after all of the `tutorial-header.scss` import. -```scss path=src/app.scss -@use './components/Info/info'; -``` - -Like our other components, `index.js` will serve as an entrypoint. Since -`Info.js` will export multiple components, we'll use the `*` wildcard in the -entrypoint export. - -```javascript path=src/components/Info/index.js -export * from './Info'; +```scss path=src/app/globals.scss +@use '@/components/Info/info'; ``` ### InfoSection component Let's create the parent component that includes the "The Principles" heading. -That markup currently looks like this in `LandingPage.js`: +That markup currently looks like this in `LandingPage`: -```jsx path=src/content/LandingPage/LandingPage.js +```jsx path=src/app/home/page.js - +

    The Principles

     - + Carbon is Open - + Carbon is Modular - + Carbon is Consistent     @@ -190,7 +182,6 @@ Using `props` we can render any heading and any number of children components (`InfoCard` that we'll build soon.) ```javascript path=src/components/Info/Info.js -import React from 'react'; import { Grid, Column } from '@carbon/react'; const InfoSection = (props) => ( @@ -249,22 +240,32 @@ In doing so, we: ## Use components Nothing is styled yet, but with our components built let's put them to use. In -`LandingPage.js`, import the components towards the top of the file. +`LandingPage`, import the components towards the top of the file. -```javascript path=src/content/LandingPage/LandingPage.js -import { InfoSection, InfoCard } from '../../components/Info'; +```javascript path=src/app/home/page.js +import { InfoSection, InfoCard } from '@/components/Info/Info'; +``` + +Next, we will install the pictograms we will use in the header. + +```bash +yarn add @carbon/pictograms-react ``` -While we're at the top of `LandingPage.js`, import the icons that we'll need as -well. +While we're at the top of `LandingPage`, import the pictograms that we'll need +as well. -```javascript path=src/content/LandingPage/LandingPage.js -import { Globe, Application, PersonFavorite } from '@carbon/react/icons'; +```javascript path=src/app/home/page.js +import { + Advocate, + Globe, + AcceleratingTransformation, +} from '@carbon/pictograms-react'; ``` With everything imported, replace the current: -```jsx path=src/content/LandingPage/LandingPage.js +```jsx path=src/app/home/page.js

    The Principles

    @@ -283,17 +284,17 @@ With everything imported, replace the current: With the new components: -```javascript path=src/content/LandingPage/LandingPage.js - +```javascript path=src/app/home/page.js + } + icon={() => } /> } + icon={() => } /> { ``` Finally, add the declaration block in `_info.scss` to set `InfoCard` body copy -styles and to bottom-align the icons. +styles and to bottom-align the pictograms. ```scss path=src/components/Info/_info.scss .info-card__body { margin-top: $spacing-06; - flex-grow: 1; // fill space so icons are bottom aligned + flex-grow: 1; // fill space so pictograms are bottom aligned @include type-style('body-long-01'); // prevent large line lengths between small and medium viewports @@ -473,7 +474,7 @@ git add --all && git commit -m "feat(tutorial): complete step 4" Then, push to your repository: ```bash -git push origin v11-react-step-4 +git push origin v11-next-step-4 ``` @@ -487,9 +488,9 @@ troubleshooting notes that may help. ### Pull request (PR) Finally, visit -[carbon-tutorial](https://github.com/carbon-design-system/carbon-tutorial) to -"Compare & pull request". In doing so, make sure that you are comparing to -`v11-react-step-4` into `base: v11-react-step-4`. +[carbon-tutorial-nextjs](https://github.com/carbon-design-system/carbon-tutorial-nextjs) +to "Compare & pull request". In doing so, make sure that you are comparing to +`v11-next-step-4` into `base: v11-next-step-4`. diff --git a/src/pages/developing/react-tutorial/step-5.mdx b/src/pages/developing/react-tutorial/step-5.mdx index 40f52821a94..63f56bb7bd7 100644 --- a/src/pages/developing/react-tutorial/step-5.mdx +++ b/src/pages/developing/react-tutorial/step-5.mdx @@ -1,8 +1,8 @@ --- -title: 5. Deploying to Github Pages +title: 5. Deploying to Vercel description: - Welcome to Carbon! This tutorial will guide you in creating a React app with - the Carbon Design System. + Welcome to Carbon! This tutorial will guide you in creating a React app using + Next.js with the Carbon Design System. tabs: [ 'Overview', @@ -21,35 +21,26 @@ import Preview from 'components/Preview'; This step takes what we've built so far and optimizes the app for a production -environment. We'll be deploying the production build to IBM Cloud. +environment. - - -**Note:** The following tutorial instructions are based on our v10 packages and -have not been updated to reflect changes for our next major version. - - - Fork, clone and branch -Build for production -Deploying to Github Pages -Submit pull request +Build for production and deploy ## Preview -A [preview](https://v11-react-step-5--carbon-tutorial.netlify.app) of what -you'll build (visually no different, but built for production): +A [preview](https://carbon-tutorial-nextjs.vercel.app/) of what you'll build +(visually no different, but built for production): @@ -94,13 +85,13 @@ yarn Then, start the app: ```bash -yarn start +yarn dev ``` You should see something similar to where the [previous step](/developing/react-tutorial/step-4) left off. -## Build for production +## Build for production and deploy Before we deploy our app, we need to create an optimized production build with this command. You may need to `CTRL-C` to stop the development environment @@ -110,110 +101,17 @@ first. yarn build ``` -Looking at `package.json`, you'll find `yarn build` to run -`react-scripts build`. This builds the app for production to the `build` folder. -It bundles React in production mode and optimizes the build for the best -performance. It even goes so far to minify files and include hashes in filenames -for caching. +Looking at `package.json`, you'll find `yarn build` to run `next build`. This +builds the app for production to the `build` folder. It bundles Next.js in +production mode and optimizes the build for the best performance. It even goes +so far to minify files and include hashes in filenames for caching. As a lot of this may seem like magic since the build configuration came from -Create React App, go ahead and check out their -[production build guidelines](https://facebook.github.io/create-react-app/docs/production-build) +Create Next App, go ahead and check out their +[going to production checklist](https://nextjs.org/docs/pages/building-your-application/deploying/production-checklist) for a full description of what's happening. -## Deploying to Github Pages - -Next we'll be deploying to -[GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages) -which allows you to host your files directly from your repository in GitHub. - -If you forked the tutorial earlier by copying only the `main` branch, you will -have to create a `gh-pages` branch with the following steps. Otherwise, if you -already have an existing `gh-pages` branch (you can easily check by going to -your repository on `github.com` and checking the existing branches), skip the -following `git` commands. - -To do this, we'll first commit our `build` folder so that git knows we have a -subtree (subfolder with our site). - -```bash -git add build && git commit -m "chore(deploy): publish build files" -``` - -Then we'll use `subtree push` to push to the `gh-pages` branch on Github. - -```bash -git subtree push --prefix build origin gh-pages -``` - -To have GitHub Pages point to the `gh-pages` branch, go to your forked Carbon -tutorial repository on `github.com`. Go to your "Settings" and under the "Pages" -tab, specify the branch, `gh-pages`, as your source. - -![Screenshot of Github settings dashboard](../shared/step-5/images/deploy-on-github-pages.png) - -Once you click save, you should be able to see your site published at the -`*.github.io/carbon-tutorial` link shown on the page. - -Congratulations! Your work is now hosted on GitHub Pages! - -## Submit pull request - -That does it! We're going to submit a pull request to verify completion of this -tutorial step. - -### Continuous integration (CI) check - -Run the CI check to make sure we're all set to submit a pull request. - -```bash -yarn ci-check -``` - - - -**Note:** Having issues running the CI check? -[Step 1]() -has troubleshooting notes that may help. - - - -### Git push - -Push to your repository: - -```bash -git push origin v11-react-step-5 -``` - - - -**Note:** Having issues pushing your changes? -[Step 1](/developing/react-tutorial/step-1#git-commit-and-push) has -troubleshooting notes that may help. - - - -### Pull request (PR) - -Finally, visit -[carbon-tutorial](https://github.com/carbon-design-system/carbon-tutorial) to -"Compare & pull request". In doing so, make sure that you are comparing to -`v11-react-step-5` into `base: v11-react-step-5`. - - - -**Note:** Expect your tutorial step PRs to be reviewed by the Carbon team but -not merged. We'll close your PR so we can keep the repository's remote branches -pristine and ready for the next person! - - - - - -**Note:** If your PR fails the CircleCI test with the error -`Can't make a request in offline mode`, try running the following command: -`rm -rf .yarn-offline-mirror node_modules && yarn cache clean && yarn install`. -Add and commit the changes once this completes, and try pushing again. - - +Next you can deploy your application to your preferred host, such as +[Vercel](https://nextjs.org/learn/basics/deploying-nextjs-app/deploy), +[IBM Cloud](https://www.ibm.com/cloud/free?utm_content=SRCWW&p1=Search&p4=43700074971942949&p5=e&gclid=CjwKCAjwjaWoBhAmEiwAXz8DBZSQ7ksqHmmFDCLGL-5erHPFytezo4q3fB6qJ13wkZROr3DYs95BGhoC6fUQAvD_BwE&gclsrc=aw.ds), +[Github Pages](https://docs.github.com/en/pages/quickstart). diff --git a/src/pages/developing/react-tutorial/wrapping-up.mdx b/src/pages/developing/react-tutorial/wrapping-up.mdx index f174e944e60..0c679f36887 100644 --- a/src/pages/developing/react-tutorial/wrapping-up.mdx +++ b/src/pages/developing/react-tutorial/wrapping-up.mdx @@ -1,19 +1,10 @@ --- title: Wrapping up description: - Welcome to Carbon! This tutorial will guide you in creating a React app with - the Carbon Design System. + Welcome to Carbon! This tutorial will guide you in creating a React app using + Next.js with the Carbon Design System. tabs: - [ - 'Overview', - 'Step 1', - 'Step 2', - 'Step 3', - 'Step 4', - 'Step 5', - 'Wrapping up', - 'FAQ', - ] + ['Overview', 'Step 1', 'Step 2', 'Step 3', 'Step 4', 'Step 5', 'Wrapping up'] --- @@ -34,4 +25,4 @@ green `status: approved` label. your username. Replace `YOURUSERNAMEHERE` with your username in the following link: - - https://github.com/carbon-design-system/carbon-tutorial/pulls?q=author%3AYOURUSERNAMEHERE + - https://github.com/carbon-design-system/carbon-tutorial-nextjs/pulls?q=author%3AYOURUSERNAMEHERE diff --git a/src/pages/developing/shared/step-2/images/landing-layout.png b/src/pages/developing/shared/step-2/images/landing-layout.png old mode 100755 new mode 100644 index efb25b46445..324bde7210d Binary files a/src/pages/developing/shared/step-2/images/landing-layout.png and b/src/pages/developing/shared/step-2/images/landing-layout.png differ diff --git a/src/pages/developing/shared/step-2/images/landing-r1-spacing.png b/src/pages/developing/shared/step-2/images/landing-r1-spacing.png index 6de986a1458..e78363add39 100644 Binary files a/src/pages/developing/shared/step-2/images/landing-r1-spacing.png and b/src/pages/developing/shared/step-2/images/landing-r1-spacing.png differ diff --git a/src/pages/developing/shared/step-2/images/landing-r1-type.png b/src/pages/developing/shared/step-2/images/landing-r1-type.png index fd25e8d8a72..58e9265864b 100644 Binary files a/src/pages/developing/shared/step-2/images/landing-r1-type.png and b/src/pages/developing/shared/step-2/images/landing-r1-type.png differ diff --git a/src/pages/developing/shared/step-2/images/landing-r2-spacing.png b/src/pages/developing/shared/step-2/images/landing-r2-spacing.png index ee2dc7c1db1..616cba5d78a 100644 Binary files a/src/pages/developing/shared/step-2/images/landing-r2-spacing.png and b/src/pages/developing/shared/step-2/images/landing-r2-spacing.png differ diff --git a/src/pages/developing/shared/step-2/images/landing-r3-spacing.png b/src/pages/developing/shared/step-2/images/landing-r3-spacing.png index 3af4a8c888b..4c0234b1de8 100644 Binary files a/src/pages/developing/shared/step-2/images/landing-r3-spacing.png and b/src/pages/developing/shared/step-2/images/landing-r3-spacing.png differ diff --git a/src/pages/developing/shared/step-4/images/info-layout.png b/src/pages/developing/shared/step-4/images/info-layout.png index ca452c619fb..49ca8921ae4 100644 Binary files a/src/pages/developing/shared/step-4/images/info-layout.png and b/src/pages/developing/shared/step-4/images/info-layout.png differ diff --git a/src/pages/developing/shared/step-4/images/info-spacing.png b/src/pages/developing/shared/step-4/images/info-spacing.png index 346a043268d..82f93c9cf04 100644 Binary files a/src/pages/developing/shared/step-4/images/info-spacing.png and b/src/pages/developing/shared/step-4/images/info-spacing.png differ