Back to React Recipes

Setting up shop: Start a React project from scratch

Before we can actually start writing React code, we need to set a few things up. We can't just include our code and libraries in <script> tags and call it a day1, since we'll be relying on JSX syntax and more recent additions to JavaScript (such as modules and classes).

We need to transform our code before it works in browsers. In particular, a React project needs:

A tool to transpile your code. A transpiler transforms your code from JSX / fancy JavaScript to normal JavaScript that works in browsers; Babel and Bublé are some popular choices.

A tool to bundle your JavaScript modules, and any code you import from npm modules, into a single JavaScript file. The bundler usually has a way to communicate with the transpiler so that your JavaScript is transformed to browser-compatible code in the process. It will also handle other types of files, such as HTML, CSS, JSON, or SVG, so you can import them in your project as you would normal JS modules. Webpack, Rollup, and Parcel are examples of bundlers.

Parcel, a bundler that works for most things we need without requiring any configuration, is a good choice for quickly setting up a React playground.

Note: I'm on macOS, but the steps should be similar enough on other operating systems.

Setting up

Prerequisites

Like many other JavaScript libraries, React is distributed through npm packages; You add it to your project with the command line.

To start a React project we need:

Create, and then initialize, your project

Make the my-project folder and navigate to it using these commands:

mdkir my-project
cd my-project

Before we can install React, we need a package.json file that lists all the dependencies in our project. We create it with:

npm init --yes

The --yes flag instructs npm to skip all the questions and just initialize a run-of-the-mill package.json that looks like this:


"name": "my-project",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC"
}

Install React and ReactDOM

We install the react and react-dom packages as dependencies to our project:

npm install react react-dom

Install the Parcel bundler

We install the Parcel bundler as a development depenency to our project — our app only depends on Parcel while we're building it2.

npm install --save-dev parcel-bundler

Create a project structure

While you can set up your project's structure in many ways, let's keep it simple and just add a couple of folders:

my-project
  dist/
  src/

src/ will hold our application's source code: HTML, JavaScript, CSS, SVG, images and all we want to include. The dist/ folder is where our app will get built, so we can deploy it to a server.

To make these folders, we can run:

mkdir src dist

Let's make an index.js file inside our src folder:

src/index.js

console.log('Hello world');

And a index.html file as well, where we fetch our index.js script:

src/index.html

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<title>My project</title>
</head>
<body>
<div id="app">
<!-- Our React App goes here -->
</div>

<script src="./index.js"></script>
</body>
</html>

If you open index.html in a browser and open the Developer Tools, you should see the Hello World message in the console. This means we've properly linked the script inside the HTML file.

Let's now configure Parcel to process our files so we can start writing some modules.

Add scripts to package.json

In package.json we add two scripts:

package.json

{
"name": "my-project",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"start": "parcel src/index.html",
"build": "parcel build src/index.html"
},
"keywords": [],
"author": "",
"license": "ISC",
"dependencies": {
"react": "^16.13.1",
"react-dom": "^16.13.1"
},
"devDependencies": {
"parcel-bundler": "^1.12.4"
}
}

Let's run the scripts! To start the development server:

npm run-script start

The command outputs:

> my-project@1.0.0 start /Users/danburzo/projects/my-project
> parcel src/index.html

Server running at http://localhost:1234
✨ Built in 1.20s.

Opening http://localhost:1234 in your browser lets you access your app. When you make changes to your source files, the app automatically reloads with the changes. To close the server, press Ctrl + C in the Terminal window.

To build an optimized bundle suitable for putting it in front of users:

npm run-script build

The command outputs:

> my-project@1.0.0 build /Users/danburzo/projects/my-project
> parcel build src/index.html

✨ Built in 1.80s.

dist/src.67e05423.js 1.13 KB 110ms
dist/src.67e05423.js.map 189 B 3ms
dist/index.html 166 B 1.63s

This builds your whole app in the dist/ folder, the content of which you can then take and put up on a server.

Now that we've set up Parcel, we can finally start writing Fancy JavaScript™.

Create your React App

Under src/, we create a components/ folder and write a simple Hello world React component:

src/components/App.js

import React from 'react';

class App extends React.Component {
render() {
return 'Hello world!';
}
}

export default App;

And then, in our index.js file, we import the module containing our React component and add it to our page.

src/index.js

import React from 'react';
import ReactDOM from 'react-dom';

import App from './components/App';

ReactDOM.render(<App />, document.getElementById('app'));

If we head back to the browser, the app should now display the message Hello world! on-screen, which means we've successfully set up a React project. 🙌

A dash of CSS

To demonstrate how to load other types of files, such as CSS, let's make a minimal stylesheet for our app:

src/style.css

body {
font-family: sans-serif;
}

In our main JS file, index.js, we import the CSS much like we would a normal JS module:

src/index.js

import React from 'react';
import ReactDOM from 'react-dom';

// importing CSS files in your app will create a CSS bundle
// that gets automatically included in your index.html file.
import './style.css';

import App from './components/App';

ReactDOM.render(<App />, document.getElementById('app'));

The browser should now show us the same Hello World! message, but now with a different font.

And that, friends, is a wrap! 🙌

Alternatives

I hope you found this article, at the end of which we have pretty much all we need to start playing with React, not too long, nor hard to follow. There are other ways to get a similar result:

A couple of notes on Git / GitHub

Not to stretch this article further, but a few quick notes if you put your project on GitHub.

First off, you should create a .gitignore file in your root folder to which you add the following lines:

node_modules/
dist/

This instructs Git not to include the two folders in version control. We don't want these hanging around on Github.

And if you're curious on how to publish the content of the dist/ folder to GitHub Pages, check out the gh-pages package.


1 Technically you can, for small experiments on your machine. You'll probably want to avoid publishing them as-is on the web, though.

2 When bundling JavaScript packages, all dependencies are technically development dependencies, because they're only ever needed as you build the project. However, it's useful to make a distinction between things that end up in the bundle and those who don't.