How to Bootstrap a React Project with IBM’s Carbon Design System (from Scratch)
[Update July 2021]
OUT OF DATE WARNING!
I get an email every week that people continue to read this article which totally blows my mind!
I’ve got to let you know though: I just re-read this and so many of the concepts outline here are horribly out of date. I’m pretty sure it still works but there are much easier ways to make this happen now!
If you’d like an updated article or some help with a project you’re working on, just leave a comment and I’ll be happy to jump in and help. I love helping make these concepts easier to understand.
I love you all very much and I believe in you, the self-taught developer. Keep pressing forward. You will eventually succeed!
Charlie
This tutorial should make it really easy for you to bootstrap a React project built on IBM’s Carbon Design System even if you don’t know a lot about all of the React lingo, packages, etc.
This tutorial assumes you’re working on a unix-based machine. If you’re working on a Windows machine, use bash on Powershell and you should be able to follow all of the instructions. Also — If you’re on Windows, you might consider the Windows Subsystem for Linux (https://docs.microsoft.com/en-us/windows/wsl/install-win10). That’ll make this super breezy.
Hopefully this takes about 15 minutes for you to do. If you have any questions, feel free to leave a comment or send me an email (chill@marketswift.com). I’ll be happy to help point you in the right direction.
Frameworks we’re using:
Feel free to skip this section and just read the tutorial — I’m only including this section so that if you get confused about a step, you’ll be able to go read and learn about the stuff that makes this app work
Here’s a list of the frameworks we’re going to be using to start our app and why we’re using them.
ReactJS (https://reactjs.org/)
ReactJS basically is an open-source JavaScript library which is used for building user interfaces specifically for single page applications.
read more(https://www.c-sharpcorner.com/article/what-and-why-reactjs/)
NextJS (https://nextjs.org/)
Next.js is a framework that most notably allows you to write server-rendered React apps easily — amongst other cool things.
read more(https://jaketrent.com/post/what-is-nextjs/)
Essentially Next will make it easier for you to add functionality to your app down the road. I recommend the tutorial found at https://nextjs.org/learn/basics/getting-started if you’re wanting to really get into this.
Carbon Design System (https://www.carbondesignsystem.com/)
Carbon is the design system for my product team at IBM Bluemix. A design system contains components that can be combined and reused to build user interfaces. It enables teams to focus on how a user interacts and converses with a piece of software, rather than arguing over what color a button should be.
read more(https://medium.com/design-ibm/carbon-designing-inside-big-blue-8577883cfe42)
Carbon will make it easy for you to build a beautiful app without having to focus on component design.
Tutorial
Step 1 — Create Your Project:
If you don’t already have NodeJS installed, you can do that by going to the Node website here: https://nodejs.org/en/download/. When you install Node, you’ll get the Node Package Manager (NPM) which will let you install React, the Carbon Design System, and more.
Once you’ve installed Node, you can create your app. We’re going to call our app “my-carbon-app”, but you’re welcome to name yours whatever you like. Use these commands to create your app:
Step 2— Add React & Next (Make Your App Run):
To add React & Next to your app, use these commands.
That first command (npm install …) installs three packages: React, React-DOM, and Next. The next two commands, (mkdir pages) and (touch pages/index.js) create a folder called “pages” and a file in pages called “index.js”. The pages folder is where you’ll store the pages in your app. index.js is the file that will contain the home page of your app.
When we ran the command “npm init -y” earlier, our computer created a file in our app’s directory called “package.json”. We’re going to edit that file to put Next in charge of serving our app. If you open package.json, you should see something that looks like this:
We’re going to change the “scripts” object. Change it to:
Great! We can now run our app. To do that, run the command:
Wow, that was easy. If you navigate to http://localhost:3000/ in your browser you’ll see your app, but unfortunately there’s a problem. Next doesn’t know what to show because we haven’t given it anything to show. Let’s give it something to show. Add the following code to “pages/index.js”:
Save the file and you should now see “Hello, world!” in your browser! Congrats on making our app! You might notice that our app isn’t very pretty. We’re going to focus on that next. Close the server with “ctrl+C” and let’s move on.
Step 3— Getting Ready for Carbon:
To make it easy to import all of the styles that will come with the Carbon Design System, we’re going to install SASS. To do that, use this command:
After installing, we need to tell NextJS what to do with the packages we just installed. We’ll do that by creating a configuration file for Next and adding some instructions to it. Let’s create a new file in the root directory of your app called “next.config.js”.
Open “next.config.js” and add the following code:
Save the file and close it. Carbon will also want to use something called Webpack. Install Webpack and create a file in the root directory of your app called “webpack.config.js”.
Open “webpack.config.js” and add the following code:
To make sure our app works with Internet Explorer, we have to add something called polyfills. To do that, create a file in the root directory of your app called “polyfills.js”.
Open “polyfills.js” and add the following code:
Save and close those files and you should be ready to go for the next part.
Step 4— Setting Up Carbon:
Here comes the fun part. Let’s install Carbon. Here’s the command:
Once that’s done, we can add styles to our project. To do that, we’re going to create a new file in the root directory of our app called “styles.scss”.
Open up “styles.scss” and add in the following code:
The last step in making sure that Carbon works is to import the stylesheet into your page. Open “pages/index.js” and add this line to the top of the file:
For reference, your “index.js” file should now look like this:
Let’s take a look at what this looks like in your browser. Restart your server with the command “npm run dev” and navigate to http://localhost:3000/.
You should notice that it looks a little less archaic! That’s because you’re no longer using Times New Roman as your font. Your text should now be in IBM Plex Sans. At this point, if you haven’t done so already and if you don’t have a ton of experience with React, you should absolutely run through the React tutorial over at https://reactjs.org/tutorial/tutorial.html.
If you have done that, then the next part will make a lot more sense to you. We’re going to add a few sample components from https://www.carbondesignsystem.com/.
Step 5 — Add some Carbon Components:
Take a minute to check out this page to learn about the components in the Carbon Design System (https://www.carbondesignsystem.com/components/overview). You can pick any component or combination of components and build React components with them. I’m going to show you how to add the UIShell to our app. You can take it from there.
Let’s replace the code in our “index.js” file with the following and walk through it together:
On line 1, we import our style sheet that we created earlier.
On lines 2 through 9 we import the Carbon components that we use in our app.
Look closer at the file paths — you’ll see that the components all live in “carbon-components-react/lib/components”. In that folder, there will be a folder that’s named the same as the component on the Carbon website. If there are subcomponents, they’ll live in that folder. If not, you can just import the component.
On lines 10 through 12 we import icons. The number (20) represents the size of the icon. You can find more icons to use here https://www.carbondesignsystem.com/guidelines/iconography/library. Just swap out the name of the icon and your desired size.
If you know about React and/or have taken a React tutorial, you’ll notice that we switched from declaring a Function as a React Component to declaring a Class as a React Component. This is because of what we’ll see in lines 15 through 17.
On lines 15 through 17, we declare a function to handle clicks that we can reference in our JSX code. (Don’t know which part is the JSX code? Take the tutorial.). You can obviously create your own functions to handle whatever you like in your own components.
On lines 21 through 59, we write up our JSX code. You can read documentation on required properties for the Carbon components at (http://react.carbondesignsystem.com/).
On line 64 we export the app for Next to do something with it.
And there you have it!
I really hope that this makes sense for anyone out there trying to bootstrap a project. If there’s something that’s unclear or that you don’t understand, feel free to send me an email and I’ll be happy to help. Here’s to bootstrapping great products!
I also want to let you know that I’m very interested in following along with your projects and helping anybody (particularly beginners) in any way that I can. You really can build whatever you set your mind to. If you need any help at all, don’t be afraid to reach out on Twitter!
