Let's start. ## Setting Up a React Project We are going to use [`create-react-app`](https://github.com/facebook/create-react-app) to scaffold easily a new React application. We can run `create-react-app` using `npx` which comes bundled with `npm 5.2+` and higher: ```shell npx create-react-app marvel-bank cd marvel-bank ``` If you use `npm 5.1` or earlier, you can't use `npx`. Instead, install `create-react-app` globally: ```shell npm install -g create-react-app ``` And then run: ```shell create-react-app marvel-bank cd marvel-bank ``` > Notice that we are not running `npm start`. As mentioned earlier, we don't need to have a running React application to use Storybook. Open the newly created `marvel-app` folder on your preferred code editor or IDE. Within `marvel-bank`, the `src` folder contains the core business logic of our React application. Let's do some housekeeping and remove files and code that we don't need. Open `src/App.js` and trim it like so: ```javascript // src/App.js import React, { Component } from "react"; import "./App.css"; class App extends Component { render() { return ; } } export default App; ``` Next, let's delete the following files: - `App.test.js` - `logo.svg` > **Spoiler**: Storybook is an essential part of our testing stack as it makes testing a painless experience. ## Using a Style Guide for Consistent Branding Using a style guide can lead to better application design and development. As explained by the [Marvel Design team](https://blog.marvelapp.com/style-guides-better-design-development/), "during the design phase style guides encourage consistency in the visual identity and help keep the interface system as logical as possible, which makes for a better UX." What is a style guide anyway? Marvel has a solid answer: "A style guide clearly demonstrates how all interface elements and components are to be visually represented. It’s essentially a master reference for the user interface (UI)." In this sense, a component library is part of a style guide as it presents our components visually and it is the single source of truth for each component (the master reference). To create a comprehensive style guide, the component library can be accompanied by design documents that define font styles and sizes as well as primary and secondary user interface colors. A Design Team usually creates a "UI Kit" that is handed to developers for implementation. _Shopify_ explains that a [UI kit is an assortment of graphic files](https://www.shopify.com/partners/blog/104547526-the-benefits-of-using-a-ui-kit) that include UI components (buttons, checkboxes, progress bars, etc.) for the purpose of defining and designing the user interface.React is such a good idea that we will spend the rest of the decade continuing to explore its implications and applications.
— Guillermo Rauch (@rauchg) November 22, 2016
## Adding SCSS to `create-react-app` We can [add `SCSS` support to `create-react-app`](https://techcookbook.com/react/use-scss-with-create-react-app) without having to `eject` to a custom setup. We need to install a few packages to help us achieve that goal: NPM: ```shell npm install --save node-sass-chokidar npm-run-all ``` [`node-sass-chokidar`](https://www.npmjs.com/package/node-sass-chokidar) is a thin wrapper around the node-sass executable to use [chokidar](https://github.com/paulmillr/chokidar) instead of [Gaze](https://github.com/shama/gaze) when watching files. [`npm-run-all`](https://www.npmjs.com/package/npm-run-all) is a CLI tool to run multiple npm-scripts in parallel or sequentially. Next, we need to modify our `package.json` `"scripts"` property to watch and process `.scss` files into `.css` ones: ```json { "name": "marvel-bank", "version": "0.1.0", "private": true, "dependencies": { "node-sass-chokidar": "^1.3.3", "npm-run-all": "^4.1.3", "react": "^16.4.1", "react-dom": "^16.4.1", "react-scripts": "1.1.4" }, "scripts": { "build-css": "node-sass-chokidar src/ -o src/", "watch-css": "npm run build-css && node-sass-chokidar src/ -o src/ --watch --recursive", "start-react": "react-scripts start", "start": "npm-run-all -p watch-css start-react", "build-react": "react-scripts build", "build": "npm-run-all -s build-css build-react", "test": "react-scripts test --env=jsdom", "eject": "react-scripts eject" } } ``` These scripts allow us to compile `.scss` files into `.css` and to keep watching the `src` folder for changes to the content of existing `.scss` files or the addition of new ones. To complete this task, we need to change the file extension of `App.css` and `index.css` to `.scss`. Depending on our development environment, this can be done in different ways such as renaming the files or refactoring their name or file type. Storybook will only understand changes made or applied in `.css` files. If we were to make a change in a `.scss` file, we would need to compile it into `.css` for Storybook to be notified of the styling changes. Normally, such compilation is a build step in our development workflow triggered by running `npm start`. However, I made the promise that we wouldn't have to run our React app in order to use Storybook in this blog post. I am keeping that promise and `npm start` is off-limits. What can we use instead? `watch-css`. As stated earlier, `watch-css` compiles our SCSS into CSS files using the `build-css` script and it keeps monitoring all the SCSS files present under the `src` directory to detect any changes. Anytime an SCSS file is changed, that file is compiled and Storybook is able to see and apply the styling changes into the component preview (as we'll see soon!). With this in mind, on the shell run the following command: ```shell npm run watch-css ``` This is a good point to make our first `git` commit. ## Using `git` Version Control Our project is in a good place for its first `git` commit. But before we do so, let's ensure that we have everything we need to ignore specified in the `.gitignore` file. If you are using an IDE like WebStorm, for example, there are extra files that the IDE creates that is better to keep out of the `git` repo. I personally like to use [`gitignore.io`](https://www.gitignore.io/) to generate the content of my `.gitignore` file automatically. The categories that I choose to create the file are WebStorm, IntelliJ, OSX, Windows, and Visual Studio Code, since they are the tools and platforms that are most commonly used. You may head to that site, enter those categories, and copy/paste the output at the end of the `.gitignore` file present in our project. Since our `.css` files are built automatically under our project configuration, we do not need to include them in version control. In the `.gitignore` file add the following rule at the end: ```text // .gitignore // ... src/**/*.css ``` This rule ensures that none of the `.css` files under the `src` folder are tracked by `git`. With a comprehensive `.gitignore` file in place, let's initialize a `git` repository (make sure that `marvel-app` directory is the current working directory): ```shell git init ``` Let's run a quick `git status` check to see what files are being untracked: ```shell git status ``` Let's go ahead and add these files shown to `git` in order to include them in our commit: ```shell git add . ``` We used a shortcut here to add all the files that were being untracked using the `.` after the `add` command. > If you want a `git` refresher, I highly recommend this amazing [_Git & Version Control_](https://www.git-tower.com/learn/) tutorial by the folks at [Git Tower](https://www.git-tower.com/). Running `git status` again would show us the new files that have been added that include changes to be committed. Let's create our first commit then: ```shell git commit -m "Initial commit" ``` We'll get a reply by `git` showing all the files that were changed and the insertions that were made. Having a well-thought commit history in place will let us go back in time if we ever need to use an older version of our code. `CTRL/CMD + Z` can only go so far back! This all looks good to me ([LGTM™](https://knowyourmeme.com/memes/lgtm)), but before we include any styling or components in our project, we need to create a sound file structure. ## Project Structure An internal pattern that we use is to have specialized folders to hold the different elements of our React application. In one of our projects, we have the following structure: ```shell - src |-- api/ |-- features/ |-- assets/ |-- redux/ |-- styles/ |-- utils/ |-- App.js |-- index.js |-- routes.js ``` For the initial phase of this project, we only need the `features` and the `styles` folder. The `features` folder holds our components in a categorized manner. We define features of our applications, such as `search` or `reports` in its subfolders, and create components that power and build that feature. What Storybook will help us solve is the event where features share components. Instead of duplicating the code across features, the feature will implement the component from a central source: our component library. As the name suggests, these common components go into a `common` feature folder. This is the project structure we want for the `src` folder in this phase of the project: ```shell - src |-- features/ |---- common/ |-- styles/ |---- _theme.scss |-- App.js |-- App.scss |-- index.js |-- index.scss |-- registerServiceWorker.js ```Oh man and a @storybookjs shoutout as well! Storybook has been indispensable for our component library.
— Maja Wichrowska (@majapw) May 17, 2018