I was about to start yet another personal project, it consists of a SPA (Single Page Application) for a travel journal.

Some time ago I tried Parcel, I really loved how simple it was to create a simple project from scratch, using Typescript + React stack. I’ve decided to create this template or base project, so next time I want to create a new SPA with my favorite frontend stack, I will only have to:

git clone https://github.com/carlosvin/react-typescript-parcel-template.git

Read this before: Parcel is not as mature as Webpack

If you want to create a production ready React application, use Webpack or better create-react-app which bring everything you need to develop a PWA with React and Typescript. Following you can find an example of an app I am developing using create-react-app: https://github.com/carlosvin/budget-tracker.

Parcel is a package bundler under development, not as mature as webpack. There are no go errors for me, at least in regards to Typescript support, see this issue in github #1378.

I still think it is a promising project, bringing more simplicity and speed to JS bundlers world, I will give it a try again for serious projects when Parcel 2 is ready, check Parcel 2 development status.

Quick start

Development server

git clone https://github.com/carlosvin/react-typescript-parcel-template.git
cd react-typescript-parcel-template
yarn install
yarn start

Last yarn start command will:

  • start a development server at {http://localhost:1234} with hot module replacement

  • build automatically development javascript files with source maps

Tip
 Each time you save a file, you will see automatically the result at {http://localhost:1234} without refreshing the page

Build production bundle

yarn build

Parcel’s default optimizations will be applied to generated files.

Files are saved at dist folder. Inside dist folder there is also a file with information about bundle content sizes: dist/report.html.

Step by step project creation

In this section I will describe how I created this project.

Firstly, create package.json with yarn init command.

yarn init

Add required dependencies

Add React dependencies.

yarn add @types/react @types/react-dom react react-dom

Previous command modifies package.json file adding dependencies section and will also install React packages in node_modules folder.

{
  "name": "project_name",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT",
  "dependencies": {
    "@types/react": "^16.7.18",
    "@types/react-dom": "^16.0.11",
    "react": "^16.7.0",
    "react-dom": "^16.7.0"
  }
}

Add Typescript compiler as development dependency.

yarn add --dev typescript

We also need Parcel bundler.

yarn add --dev parcel-bundler

I’ve added a non-required dependency, it is a plugin to generate a report of generated bundle contents (the parcel version of webpack-bundle-analyzer.

yarn add --dev parcel-plugin-bundle-visualiser

Create application source code

First we create the React application in src/index.tsx file.

import * as React from "react";
import * as ReactDOM from "react-dom";

class App extends React.PureComponent {
    render() {
        return <h1>Hello world!</h1>;
    }
}

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

Parcel can take index.html file as entry file and it figures out how to build the application, so let’s create src/index.html as follows:

<html>
  <body>
    <div id="app"></div>
    <script src="./index.tsx"></script>
  </body>
</html>

We need div tag for React to inject the DOM elements. The script declaration is used by Parcel to find entry point to build.

Add commands build the project

I’ve added the commands:

  • build: Check "Build production bundle" section.

  • start: Check "Development server" section.

    "scripts": {
        "start": "parcel src/index.html",
        "build": "parcel build src/index.html"
    }

Then to it is really easy to:

  • run development server: yarn start

  • generate a production bundle: yarn build

There is another approach described in Parcel documentation that consists of installing Parcel globally.

I’ve opted for more isolated approach that affects only project you are working on, you just install Parcel as devDependency. There is a tiny drawback, you can’t just run parcel index.html, because it is not installed in your system, but in node_modules.

There is a simple way to run any binary installed in node_modules, you can just run npx parcel index.html.

I like more to define build steps in package.json file, so you can have well defined commands more suited to build your project. You can also use these commands as documentation how to build your project.

Configure Typescript (optional)

Create a tsconfig.json file
{
    "compilerOptions": {
        "outDir": "./dist/",
        "sourceMap": true,
        "noImplicitAny": true,
        "module": "commonjs",
        "target": "es5",
        "jsx": "react"
    }
}

With this configuration, Typescript compiler will:

  • Generate files in dist folder.

  • Generate source maps.

  • Will not allow to declare any type, for example following declaration is not allowed: const elements: any;

  • Generated module code will be CommonJs.

  • Generated code will be ECMAScript 5 compliant.

  • Support JSX in .tsx files.

Full source code

You can find full example at: https://github.com/carlosvin/react-typescript-parcel-template.

Or you can directly download the source code: