{"componentChunkName":"component---src-pages-tutorial-react-step-1-mdx","path":"/tutorial/react/step-1/","result":{"pageContext":{"frontmatter":{"title":"1. Installing Carbon","description":"Welcome to Carbon! This tutorial will guide you in creating a React app with the Carbon Design System.","tabs":["Overview","Step 1","Step 2","Step 3","Step 4","Step 5","Wrapping up"]},"relativePagePath":"/tutorial/react/step-1.mdx","titleType":"prepend","MdxNode":{"id":"29fd914d-3e50-5795-9ab4-fdd68b538784","children":[],"parent":"8a803423-454c-5bfe-8cb9-4a9eddec5081","internal":{"content":"---\ntitle: 1. Installing Carbon\ndescription: Welcome to Carbon! This tutorial will guide you in creating a React app with the Carbon Design System.\ntabs:\n ['Overview', 'Step 1', 'Step 2', 'Step 3', 'Step 4', 'Step 5', 'Wrapping up']\n---\n\nimport Preview from 'components/Preview';\n\n\n\nStarting with Create React App, let's install Carbon and begin using Carbon\ncomponents. By the end you will have a React app that uses the UI Shell to\nnavigate between pages.\n\n\n\n\n\nFork, clone and branch\nBuild and start\nInstall Carbon\nInstall and build Sass\nAdd UI Shell\nCreate pages\nAdd routing\nSubmit pull request\n\n\n\n## Preview\n\nA [preview](https://react-step-2--carbon-tutorial.netlify.com) of what you will build:\n\n\n\n## Fork, clone and branch\n\nThis tutorial has an accompanying GitHub repository called [carbon-tutorial](https://github.com/carbon-design-system/carbon-tutorial) that we'll use as a starting point for each step.\n\n### Fork\n\nTo begin, fork [carbon-tutorial](https://github.com/carbon-design-system/carbon-tutorial) using your GitHub account.\n\n### Clone\n\nGo to your forked repository, copy the SSH or HTTPS URL and in your terminal run the two commands to get the repository in your local file system and enter that directory.\n\n```bash\n$ git clone [your fork SSH/HTTPS]\n$ cd carbon-tutorial\n```\n\n### Add upstream remote\n\nAdd a remote called `upstream` so we can eventually submit a pull request once you have completed this tutorial step.\n\n```bash\n$ git remote add upstream git@github.com:carbon-design-system/carbon-tutorial.git\n```\n\nOr, if you prefer to use HTTPS instead of SSH with your remotes:\n\n```bash\n$ git remote add upstream https://github.com/carbon-design-system/carbon-tutorial.git\n```\n\nVerify that your forked repository remotes are correct:\n\n```bash\n$ git remote -v\n```\n\nYour terminal should output something like this:\n\n```bash\norigin\t[your forked repo] (fetch)\norigin\t[your forked repo] (push)\nupstream\tgit@github.com:carbon-design-system/carbon-tutorial.git (fetch)\nupstream\tgit@github.com:carbon-design-system/carbon-tutorial.git (push)\n```\n\n### Branch\n\nNow that we have our repository set up, let's check out the branch for this tutorial step's starting point. Run the two commands:\n\n```bash\n$ git fetch upstream\n$ git checkout -b react-step-1 upstream/react-step-1\n```\n\n## Build and start\n\nWe have the repository forked to your GitHub account, cloned down to your machine, and the starting branch checked out. Next, install the React app's dependencies with:\n\n```bash\n$ yarn\n```\n\nAfter the dependencies are installed, you can start the app with:\n\n```bash\n$ yarn start\n```\n\nYour default browser should open up with an empty page that says: `Hello Carbon! Well, not quite yet. This is the starting point for the Carbon tutorial.`\n\n## Install Carbon\n\nEven though we installed existing dependencies, we've yet to install the Carbon packages.\n\n- `carbon-components` - component styles\n- `carbon-components-react` - React components\n- `@carbon/icons-react` - React icons\n\nStop your development server with `CTRL-C` and install Carbon dependencies with:\n\n```bash\n$ yarn add carbon-components carbon-components-react @carbon/icons-react\n```\n\n## Install and build Sass\n\nWe need to run a Sass build as the Carbon styles are authored in Sass, so run the following command to install `node-sass` as a dependency.\n\n```bash\n$ yarn add node-sass\n```\n\nTo avoid having to add the `~` prefix when importing SCSS files from `node_modules`, create a `.env` file at the project root that contains:\n\n```bash path=.env\nSASS_PATH=\"node_modules\"\n```\n\nFor the Windows operating system, use:\n\n```bash path=.env\nSASS_PATH=./node_modules\n```\n\nThen, start the app again. If your app's currently running, you'll need to restart it for the new environment variable to be used.\n\n```bash\n$ yarn start\n```\n\nThe app looks as it did before. Next, let's prepare our app for a Sass build.\n\nIn the `src` directory, rename `index.css` as `index.scss`. Then in `index.js` update the `index.css` import to `index.scss`.\n\n### Import carbon-component styles\n\nIn `index.scss`, import the Carbon styles by adding the following at the top of the file:\n\n```scss path=src/index.scss\n@import 'carbon-components/scss/globals/scss/styles.scss';\n```\n\nMaking this change to `index.scss` will cause all of the Carbon Sass to re-compile. Once finished re-compiling the Carbon base styling is applied (IBM Plex Sans font family, font size, weight, colors, etc.)\n\nRe-compiling all of the Carbon Sass takes a while, even on fast systems. Let's speed this up by moving our custom app Sass into a separate file, `app.scss` in the 'src' directory, and import that from `App.js`.\n\n```javascript path=src/App.js\nimport './app.scss';\n```\n\nBy modifying `index.scss` as little as possible and storing all app-specific styling in `app.scss` we will make compile times much quicker. Storing the app-specific styling in a separate file also makes good organizational sense.\n\nNext we'll import a `Button` from Carbon to test that our dependencies are working properly. At the top of `App.js`, import the `Button` by adding the following:\n\n```javascript path=src/App.js\nimport { Button } from 'carbon-components-react';\n```\n\nIn the `App` component return, you can now replace:\n\n\n```html path=src/App.js\n
\n Hello Carbon! Well, not quite yet. This is the starting point for the Carbon tutorial.\n
\n```\n\n\nwith:\n\n\n```html path=src/App.js\n\n```\n\n\nCongratulations, you've imported your first component! You should see a Carbon styled button on the page.\n\n## Add UI Shell\n\n_Note: The UI Shell has experimental status at the moment. We do not recommend using it for production until it is stable, but if doing so, know that there may be breaking changes in the future._\n\nNext we're going to create a React component called `TutorialHeader` to use with the UI Shell Carbon component. In the `src` directory, create a `components` directory and inside of that, a `TutorialHeader` directory. Create the following files inside `src/components/TutorialHeader`:\n\n```bash\nsrc/components/TutorialHeader\n├──_tutorial-header.scss\n├──index.js\n└──TutorialHeader.js\n```\n\n### Add UI Shell Sass\n\nIn `index.scss` add the following feature-flag **above** the Carbon styles import like so:\n\n```scss path=src/index.scss\n$feature-flags: (\n ui-shell: true,\n);\n```\n\nThis is because our UI Shell is in experimental mode and the styles need to be manually imported.\n\nNext, in `app.scss`, we'll import our `TutorialHeader` styles. Your file should now look like this:\n\n```scss path=src/app.scss\n@import './components/TutorialHeader/tutorial-header.scss';\n```\n\n### Import and export the header\n\nIn `src/components/TutorialHeader/index.js`, import and export our `TutorialHeader` component like so:\n\n```javascript path=src/components/TutorialHeader/index.js\nimport TutorialHeader from './TutorialHeader';\nexport default TutorialHeader;\n```\n\nNext we'll import our Carbon UI Shell components into `TutorialHeader.js`. Set up the file like so:\n\n```javascript path=src/components/TutorialHeader/TutorialHeader.js\nimport React from 'react';\nimport {\n Header,\n HeaderName,\n HeaderNavigation,\n HeaderMenuItem,\n HeaderGlobalBar,\n HeaderGlobalAction,\n SkipToContent,\n} from 'carbon-components-react/lib/components/UIShell';\n\nconst TutorialHeader = () => (\n
\n \n \n Carbon Tutorial\n \n \n Repositories\n \n \n
\n);\n\nexport default TutorialHeader;\n```\n\n_Note: you can find a description of the different components used UI Shell in our [carbon-components-react](https://github.com/carbon-design-system/carbon/tree/master/packages/react/src/components/UIShell) package._\n\n_Note: When creating navigation headers, it's important to have a_ `Skip to content` _link so keyboard users can skip the navigation items and go straight to the main content._\n\n_Note: It's important that the_ `TutorialHeader` _returns the Carbon_ `Header` _as it's containing element, as we'll later be rendering_ `TutorialHeader` _in_ `App.js` _as a preceeding sibling of_ `Content`_, another UI Shell component. Those components need to live one after another for the UI Shell to properly render._\n\n### Import icons\n\nNow let's import the icons from our `@carbon/icons-react` elements package. In the `TutorialHeader.js` file, we need to import each individual icon we will use.\n\n```javascript path=src/components/TutorialHeader/TutorialHeader.js\nimport Notification20 from '@carbon/icons-react/lib/notification/20';\nimport UserAvatar20 from '@carbon/icons-react/lib/user--avatar/20';\nimport AppSwitcher20 from '@carbon/icons-react/lib/app-switcher/20';\n```\n\nThen we need to add the `HeaderGlobalAction` component inside of the `HeaderGlobalBar` where we will add our icons. These represent actions in the header a user can make. Replace:\n\n```html path=src/components/TutorialHeader/TutorialHeader.js\n\n```\n\nWith:\n\n```html path=src/components/TutorialHeader/TutorialHeader.js\n\n \n \n \n \n \n \n \n \n \n\n```\n\n### Render the header\n\nNext we'll render our UI Shell by importing our `TutorialHeader` component and `Content` into `App.js`. Your imports should look like this:\n\n```javascript path=src/App.js\nimport React, { Component } from 'react';\nimport './app.scss';\nimport { Button } from 'carbon-components-react';\nimport { Content } from 'carbon-components-react/lib/components/UIShell';\nimport TutorialHeader from './components/TutorialHeader';\n```\n\nOur `return` currently just contains a `Button`. Let's update that to include our imported components. This should look like the following:\n\n```javascript path=src/App.js\nclass App extends Component {\n render() {\n return (\n <>\n \n \n \n \n \n );\n }\n}\n```\n\nYou should now see a styled UI Shell header and a button below it.\n\n## Create pages\n\nNext 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`.\n\nSince our app will have two pages, we'll create two folders in `src/content`.\n\n```bash\nsrc/content\n├── LandingPage\n└── RepoPage\n```\n\nNext we'll set up these folders the same way we set up `src/components/TutorialHeader`.\n\nCreate the following files in the `LandingPage` folder:\n\n```bash\nsrc/content/LandingPage\n├── _landing-page.scss\n├── index.js\n└── LandingPage.js\n```\n\nCreate the following files in the `RepoPage` folder:\n\n```bash\nsrc/content/RepoPage\n├── _repo-page.scss\n├── index.js\n└── RepoPage.js\n```\n\n### Set up content Sass\n\nNext, we'll import our content Sass files in `app.scss`, like so:\n\n```scss path=src/app.scss\n@import './components/TutorialHeader/tutorial-header.scss';\n@import './content/LandingPage/landing-page.scss';\n@import './content/RepoPage/repo-page.scss';\n```\n\n### Import and export content pages\n\nNow 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:\n\n```javascript path=src/content/LandingPage/index.js\nimport LandingPage from './LandingPage';\nexport default LandingPage;\n```\n\nNext in `LandingPage.js` we'll create our component.\n\n```javascript path=src/content/LandingPage/LandingPage.js\nimport React from 'react';\n\nconst LandingPage = () => {\n return
LANDING PAGE
;\n};\n\nexport default LandingPage;\n```\n\nWe'll repeat this process with `RepoPage`.\n\nIn `src/content/RepoPage/index.js`, import and export the `RepoPage` component like so:\n\n```javascript path=src/content/RepoPage/index.js\nimport RepoPage from './RepoPage';\nexport default RepoPage;\n```\n\nThen in `RepoPage.js` create the component.\n\n```javascript path=src/content/RepoPage/RepoPage.js\nimport React from 'react';\n\nconst RepoPage = () => {\n return
REPO PAGE
;\n};\n\nexport default RepoPage;\n```\n\nAwesome! We've just created our content pages. Next thing we need to do is render them with our router.\n\n## Add routing\n\nWe'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:\n\n```bash\n$ yarn add react-router-dom\n$ yarn start\n```\n\nFirst, we need to wrap our app in the `Router` component. In the root `index.js`, add the import:\n\n```javascript path=src/index.js\nimport { HashRouter as Router } from 'react-router-dom';\n```\n\n_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)._\n\nThen, update the `render()` function to include the `Router`.\n\n```javascript path=src/index.js\nReactDOM.render(\n \n \n ,\n document.getElementById('root')\n);\n```\n\nIn order to render our content pages, we need to add the following imports in `App.js` below our existing imports.\n\n```javascript path=src/App.js\nimport { Route, Switch } from 'react-router-dom';\nimport LandingPage from './content/LandingPage';\nimport RepoPage from './content/RepoPage';\n```\n\nThis allows us to use our page content components and routing components from `react-router-dom`.\n\nNext thing we need to is update what we're returning in `App.js` . We currently just have a button in our content. In order to render our pages correctly, we need to delete the `Button` component within `Content` (and remove the Button import).\n\nNow inside `Content` we'll add the following:\n\n\n```html path=src/App.js\n\n \n \n\n```\n\n\nAfter that we need to do a couple quick fixes to the UI Shell to have it work with the React router.\n\nAdd the `Link` import in `TutorialHeader.js`:\n\n```javascript path=src/components/TutorialHeader/TutorialHeader.js\nimport { Link } from 'react-router-dom';\n```\n\nWe 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`:\n\n```javascript path=src/components/TutorialHeader/TutorialHeader.js\n\n Carbon Tutorial\n\n```\n\nDo the same with the component that contains `href=\"/repos\"`, updating to:\n\n```javascript path=src/components/TutorialHeader/TutorialHeader.js\n\n Repositories\n\n```\n\nYou should now have a working header that routes to different pages without full page reload!\n\n## Submit pull request\n\nWe're going to submit a pull request to verify completion of this tutorial step and demonstrate a couple related concepts.\n\n### Continuous integration (CI) check\n\nWe have a `ci-check` script defined in `package.json` that verifies file formatting for files that have been touched since the last Git commit with a tool called [Prettier](https://prettier.io). You'd typically also have that script run your test suite as part of your CI build. Go ahead and make sure everything looks good with:\n\n```bash\n$ yarn ci-check\n```\n\n_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`_._\n\n### Git commit and push\n\nBefore we can create a pull request, stage and commit all of your changes:\n\n```bash\n$ git add --all && git commit -m \"feat(tutorial): complete step 1\"\n```\n\n_Note: You'll notice that your commit includes binaries in the _`.yarn-offline-mirror`_ folder. That's expected as the repository is configured to run [Yarn offline](https://yarnpkg.com/blog/2016/11/24/offline-mirror) for more reliable builds. Future tutorial steps that don't install new packages won't have _`.yarn-offline-mirror`_ commit changes._\n\nThen, push to your repository:\n\n```bash\n$ git push origin react-step-1\n```\n\n_Note: If your Git remote protocol is HTTPS instead of SSH, you may be prompted to authenticate with GitHub when you push changes. If your GitHub account has two-factor authentication enabled, we recommend that you follow these instructions to [create a personal access token for the command line](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line). That lets you use your token instead of password when performing Git operations over HTTPS._\n\n_Note: If you receive a_ `non-fast-forward` _error, it's likely that your forked repository is behind the original repository and needs updated. This can happen if the tutorial was updated after you began working on it. To fix, run_ `git pull upstream react-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._\n\n### Pull request (PR)\n\nFinally, 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 `react-step-1` into `base: react-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.\n\n_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!_\n","type":"Mdx","contentDigest":"c6bab3d953226be93472d431c1186fec","counter":1689,"owner":"gatsby-plugin-mdx"},"frontmatter":{"title":"1. Installing Carbon","description":"Welcome to Carbon! This tutorial will guide you in creating a React app with the Carbon Design System.","tabs":["Overview","Step 1","Step 2","Step 3","Step 4","Step 5","Wrapping up"]},"exports":{},"rawBody":"---\ntitle: 1. Installing Carbon\ndescription: Welcome to Carbon! This tutorial will guide you in creating a React app with the Carbon Design System.\ntabs:\n ['Overview', 'Step 1', 'Step 2', 'Step 3', 'Step 4', 'Step 5', 'Wrapping up']\n---\n\nimport Preview from 'components/Preview';\n\n\n\nStarting with Create React App, let's install Carbon and begin using Carbon\ncomponents. By the end you will have a React app that uses the UI Shell to\nnavigate between pages.\n\n\n\n\n\nFork, clone and branch\nBuild and start\nInstall Carbon\nInstall and build Sass\nAdd UI Shell\nCreate pages\nAdd routing\nSubmit pull request\n\n\n\n## Preview\n\nA [preview](https://react-step-2--carbon-tutorial.netlify.com) of what you will build:\n\n\n\n## Fork, clone and branch\n\nThis tutorial has an accompanying GitHub repository called [carbon-tutorial](https://github.com/carbon-design-system/carbon-tutorial) that we'll use as a starting point for each step.\n\n### Fork\n\nTo begin, fork [carbon-tutorial](https://github.com/carbon-design-system/carbon-tutorial) using your GitHub account.\n\n### Clone\n\nGo to your forked repository, copy the SSH or HTTPS URL and in your terminal run the two commands to get the repository in your local file system and enter that directory.\n\n```bash\n$ git clone [your fork SSH/HTTPS]\n$ cd carbon-tutorial\n```\n\n### Add upstream remote\n\nAdd a remote called `upstream` so we can eventually submit a pull request once you have completed this tutorial step.\n\n```bash\n$ git remote add upstream git@github.com:carbon-design-system/carbon-tutorial.git\n```\n\nOr, if you prefer to use HTTPS instead of SSH with your remotes:\n\n```bash\n$ git remote add upstream https://github.com/carbon-design-system/carbon-tutorial.git\n```\n\nVerify that your forked repository remotes are correct:\n\n```bash\n$ git remote -v\n```\n\nYour terminal should output something like this:\n\n```bash\norigin\t[your forked repo] (fetch)\norigin\t[your forked repo] (push)\nupstream\tgit@github.com:carbon-design-system/carbon-tutorial.git (fetch)\nupstream\tgit@github.com:carbon-design-system/carbon-tutorial.git (push)\n```\n\n### Branch\n\nNow that we have our repository set up, let's check out the branch for this tutorial step's starting point. Run the two commands:\n\n```bash\n$ git fetch upstream\n$ git checkout -b react-step-1 upstream/react-step-1\n```\n\n## Build and start\n\nWe have the repository forked to your GitHub account, cloned down to your machine, and the starting branch checked out. Next, install the React app's dependencies with:\n\n```bash\n$ yarn\n```\n\nAfter the dependencies are installed, you can start the app with:\n\n```bash\n$ yarn start\n```\n\nYour default browser should open up with an empty page that says: `Hello Carbon! Well, not quite yet. This is the starting point for the Carbon tutorial.`\n\n## Install Carbon\n\nEven though we installed existing dependencies, we've yet to install the Carbon packages.\n\n- `carbon-components` - component styles\n- `carbon-components-react` - React components\n- `@carbon/icons-react` - React icons\n\nStop your development server with `CTRL-C` and install Carbon dependencies with:\n\n```bash\n$ yarn add carbon-components carbon-components-react @carbon/icons-react\n```\n\n## Install and build Sass\n\nWe need to run a Sass build as the Carbon styles are authored in Sass, so run the following command to install `node-sass` as a dependency.\n\n```bash\n$ yarn add node-sass\n```\n\nTo avoid having to add the `~` prefix when importing SCSS files from `node_modules`, create a `.env` file at the project root that contains:\n\n```bash path=.env\nSASS_PATH=\"node_modules\"\n```\n\nFor the Windows operating system, use:\n\n```bash path=.env\nSASS_PATH=./node_modules\n```\n\nThen, start the app again. If your app's currently running, you'll need to restart it for the new environment variable to be used.\n\n```bash\n$ yarn start\n```\n\nThe app looks as it did before. Next, let's prepare our app for a Sass build.\n\nIn the `src` directory, rename `index.css` as `index.scss`. Then in `index.js` update the `index.css` import to `index.scss`.\n\n### Import carbon-component styles\n\nIn `index.scss`, import the Carbon styles by adding the following at the top of the file:\n\n```scss path=src/index.scss\n@import 'carbon-components/scss/globals/scss/styles.scss';\n```\n\nMaking this change to `index.scss` will cause all of the Carbon Sass to re-compile. Once finished re-compiling the Carbon base styling is applied (IBM Plex Sans font family, font size, weight, colors, etc.)\n\nRe-compiling all of the Carbon Sass takes a while, even on fast systems. Let's speed this up by moving our custom app Sass into a separate file, `app.scss` in the 'src' directory, and import that from `App.js`.\n\n```javascript path=src/App.js\nimport './app.scss';\n```\n\nBy modifying `index.scss` as little as possible and storing all app-specific styling in `app.scss` we will make compile times much quicker. Storing the app-specific styling in a separate file also makes good organizational sense.\n\nNext we'll import a `Button` from Carbon to test that our dependencies are working properly. At the top of `App.js`, import the `Button` by adding the following:\n\n```javascript path=src/App.js\nimport { Button } from 'carbon-components-react';\n```\n\nIn the `App` component return, you can now replace:\n\n\n```html path=src/App.js\n
\n Hello Carbon! Well, not quite yet. This is the starting point for the Carbon tutorial.\n
\n```\n\n\nwith:\n\n\n```html path=src/App.js\n\n```\n\n\nCongratulations, you've imported your first component! You should see a Carbon styled button on the page.\n\n## Add UI Shell\n\n_Note: The UI Shell has experimental status at the moment. We do not recommend using it for production until it is stable, but if doing so, know that there may be breaking changes in the future._\n\nNext we're going to create a React component called `TutorialHeader` to use with the UI Shell Carbon component. In the `src` directory, create a `components` directory and inside of that, a `TutorialHeader` directory. Create the following files inside `src/components/TutorialHeader`:\n\n```bash\nsrc/components/TutorialHeader\n├──_tutorial-header.scss\n├──index.js\n└──TutorialHeader.js\n```\n\n### Add UI Shell Sass\n\nIn `index.scss` add the following feature-flag **above** the Carbon styles import like so:\n\n```scss path=src/index.scss\n$feature-flags: (\n ui-shell: true,\n);\n```\n\nThis is because our UI Shell is in experimental mode and the styles need to be manually imported.\n\nNext, in `app.scss`, we'll import our `TutorialHeader` styles. Your file should now look like this:\n\n```scss path=src/app.scss\n@import './components/TutorialHeader/tutorial-header.scss';\n```\n\n### Import and export the header\n\nIn `src/components/TutorialHeader/index.js`, import and export our `TutorialHeader` component like so:\n\n```javascript path=src/components/TutorialHeader/index.js\nimport TutorialHeader from './TutorialHeader';\nexport default TutorialHeader;\n```\n\nNext we'll import our Carbon UI Shell components into `TutorialHeader.js`. Set up the file like so:\n\n```javascript path=src/components/TutorialHeader/TutorialHeader.js\nimport React from 'react';\nimport {\n Header,\n HeaderName,\n HeaderNavigation,\n HeaderMenuItem,\n HeaderGlobalBar,\n HeaderGlobalAction,\n SkipToContent,\n} from 'carbon-components-react/lib/components/UIShell';\n\nconst TutorialHeader = () => (\n
\n \n \n Carbon Tutorial\n \n \n Repositories\n \n \n
\n);\n\nexport default TutorialHeader;\n```\n\n_Note: you can find a description of the different components used UI Shell in our [carbon-components-react](https://github.com/carbon-design-system/carbon/tree/master/packages/react/src/components/UIShell) package._\n\n_Note: When creating navigation headers, it's important to have a_ `Skip to content` _link so keyboard users can skip the navigation items and go straight to the main content._\n\n_Note: It's important that the_ `TutorialHeader` _returns the Carbon_ `Header` _as it's containing element, as we'll later be rendering_ `TutorialHeader` _in_ `App.js` _as a preceeding sibling of_ `Content`_, another UI Shell component. Those components need to live one after another for the UI Shell to properly render._\n\n### Import icons\n\nNow let's import the icons from our `@carbon/icons-react` elements package. In the `TutorialHeader.js` file, we need to import each individual icon we will use.\n\n```javascript path=src/components/TutorialHeader/TutorialHeader.js\nimport Notification20 from '@carbon/icons-react/lib/notification/20';\nimport UserAvatar20 from '@carbon/icons-react/lib/user--avatar/20';\nimport AppSwitcher20 from '@carbon/icons-react/lib/app-switcher/20';\n```\n\nThen we need to add the `HeaderGlobalAction` component inside of the `HeaderGlobalBar` where we will add our icons. These represent actions in the header a user can make. Replace:\n\n```html path=src/components/TutorialHeader/TutorialHeader.js\n\n```\n\nWith:\n\n```html path=src/components/TutorialHeader/TutorialHeader.js\n\n \n \n \n \n \n \n \n \n \n\n```\n\n### Render the header\n\nNext we'll render our UI Shell by importing our `TutorialHeader` component and `Content` into `App.js`. Your imports should look like this:\n\n```javascript path=src/App.js\nimport React, { Component } from 'react';\nimport './app.scss';\nimport { Button } from 'carbon-components-react';\nimport { Content } from 'carbon-components-react/lib/components/UIShell';\nimport TutorialHeader from './components/TutorialHeader';\n```\n\nOur `return` currently just contains a `Button`. Let's update that to include our imported components. This should look like the following:\n\n```javascript path=src/App.js\nclass App extends Component {\n render() {\n return (\n <>\n \n \n \n \n \n );\n }\n}\n```\n\nYou should now see a styled UI Shell header and a button below it.\n\n## Create pages\n\nNext 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`.\n\nSince our app will have two pages, we'll create two folders in `src/content`.\n\n```bash\nsrc/content\n├── LandingPage\n└── RepoPage\n```\n\nNext we'll set up these folders the same way we set up `src/components/TutorialHeader`.\n\nCreate the following files in the `LandingPage` folder:\n\n```bash\nsrc/content/LandingPage\n├── _landing-page.scss\n├── index.js\n└── LandingPage.js\n```\n\nCreate the following files in the `RepoPage` folder:\n\n```bash\nsrc/content/RepoPage\n├── _repo-page.scss\n├── index.js\n└── RepoPage.js\n```\n\n### Set up content Sass\n\nNext, we'll import our content Sass files in `app.scss`, like so:\n\n```scss path=src/app.scss\n@import './components/TutorialHeader/tutorial-header.scss';\n@import './content/LandingPage/landing-page.scss';\n@import './content/RepoPage/repo-page.scss';\n```\n\n### Import and export content pages\n\nNow 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:\n\n```javascript path=src/content/LandingPage/index.js\nimport LandingPage from './LandingPage';\nexport default LandingPage;\n```\n\nNext in `LandingPage.js` we'll create our component.\n\n```javascript path=src/content/LandingPage/LandingPage.js\nimport React from 'react';\n\nconst LandingPage = () => {\n return
LANDING PAGE
;\n};\n\nexport default LandingPage;\n```\n\nWe'll repeat this process with `RepoPage`.\n\nIn `src/content/RepoPage/index.js`, import and export the `RepoPage` component like so:\n\n```javascript path=src/content/RepoPage/index.js\nimport RepoPage from './RepoPage';\nexport default RepoPage;\n```\n\nThen in `RepoPage.js` create the component.\n\n```javascript path=src/content/RepoPage/RepoPage.js\nimport React from 'react';\n\nconst RepoPage = () => {\n return
REPO PAGE
;\n};\n\nexport default RepoPage;\n```\n\nAwesome! We've just created our content pages. Next thing we need to do is render them with our router.\n\n## Add routing\n\nWe'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:\n\n```bash\n$ yarn add react-router-dom\n$ yarn start\n```\n\nFirst, we need to wrap our app in the `Router` component. In the root `index.js`, add the import:\n\n```javascript path=src/index.js\nimport { HashRouter as Router } from 'react-router-dom';\n```\n\n_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)._\n\nThen, update the `render()` function to include the `Router`.\n\n```javascript path=src/index.js\nReactDOM.render(\n \n \n ,\n document.getElementById('root')\n);\n```\n\nIn order to render our content pages, we need to add the following imports in `App.js` below our existing imports.\n\n```javascript path=src/App.js\nimport { Route, Switch } from 'react-router-dom';\nimport LandingPage from './content/LandingPage';\nimport RepoPage from './content/RepoPage';\n```\n\nThis allows us to use our page content components and routing components from `react-router-dom`.\n\nNext thing we need to is update what we're returning in `App.js` . We currently just have a button in our content. In order to render our pages correctly, we need to delete the `Button` component within `Content` (and remove the Button import).\n\nNow inside `Content` we'll add the following:\n\n\n```html path=src/App.js\n\n \n \n\n```\n\n\nAfter that we need to do a couple quick fixes to the UI Shell to have it work with the React router.\n\nAdd the `Link` import in `TutorialHeader.js`:\n\n```javascript path=src/components/TutorialHeader/TutorialHeader.js\nimport { Link } from 'react-router-dom';\n```\n\nWe 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`:\n\n```javascript path=src/components/TutorialHeader/TutorialHeader.js\n\n Carbon Tutorial\n\n```\n\nDo the same with the component that contains `href=\"/repos\"`, updating to:\n\n```javascript path=src/components/TutorialHeader/TutorialHeader.js\n\n Repositories\n\n```\n\nYou should now have a working header that routes to different pages without full page reload!\n\n## Submit pull request\n\nWe're going to submit a pull request to verify completion of this tutorial step and demonstrate a couple related concepts.\n\n### Continuous integration (CI) check\n\nWe have a `ci-check` script defined in `package.json` that verifies file formatting for files that have been touched since the last Git commit with a tool called [Prettier](https://prettier.io). You'd typically also have that script run your test suite as part of your CI build. Go ahead and make sure everything looks good with:\n\n```bash\n$ yarn ci-check\n```\n\n_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`_._\n\n### Git commit and push\n\nBefore we can create a pull request, stage and commit all of your changes:\n\n```bash\n$ git add --all && git commit -m \"feat(tutorial): complete step 1\"\n```\n\n_Note: You'll notice that your commit includes binaries in the _`.yarn-offline-mirror`_ folder. That's expected as the repository is configured to run [Yarn offline](https://yarnpkg.com/blog/2016/11/24/offline-mirror) for more reliable builds. Future tutorial steps that don't install new packages won't have _`.yarn-offline-mirror`_ commit changes._\n\nThen, push to your repository:\n\n```bash\n$ git push origin react-step-1\n```\n\n_Note: If your Git remote protocol is HTTPS instead of SSH, you may be prompted to authenticate with GitHub when you push changes. If your GitHub account has two-factor authentication enabled, we recommend that you follow these instructions to [create a personal access token for the command line](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line). That lets you use your token instead of password when performing Git operations over HTTPS._\n\n_Note: If you receive a_ `non-fast-forward` _error, it's likely that your forked repository is behind the original repository and needs updated. This can happen if the tutorial was updated after you began working on it. To fix, run_ `git pull upstream react-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._\n\n### Pull request (PR)\n\nFinally, 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 `react-step-1` into `base: react-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.\n\n_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!_\n","fileAbsolutePath":"/zeit/1dde86ed/src/pages/tutorial/react/step-1.mdx"}}}}