Parcel works great for building single or multi-page React applications. It includes a first-class development experience with Fast Refresh, and supports JSX, TypeScript, Flow, and many styling methodologies out of the box.
react-dom into your project:
yarn add react react-dom
Most Parcel apps start with an HTML file. Parcel follows the dependencies (such as a
<script> tag) from there to build your app.
As you can see, we’ve referenced
index.js from a
<script> element in our HTML file. This imported
react-dom and used it to render our
App component into the
<div id="app"> element in our page.
See Building a web app with Parcel for more details on getting started with a new project.
Parcel supports JSX automatically when it detects you are using React. If you’re using React 17 or later, it also automatically enables the modern JSX transform, which means you don't even need to import React for JSX to work, as you can see in
App.js in the above example.
Parcel has first-class support for React Fast Refresh, which gives you quick feedback as you edit your code without needing to reload the page. In most cases, it can preserve component state as code is edited, even if you make an error. See the Hot reloading docs for details on how this works.
- Avoid class components – Fast Refresh only works with function components (and Hooks).
- Export only React components – If a file exports a mix of React components and other types of values, its state will be reset whenever it changes. To preserve state, only export React components and move other exports to a different file if possible.
- Avoid unnamed default exports – Declaring components using a default exported arrow function will cause state to be reset when it is changed. Use a named function, or assign the arrow function to a variable instead.
- Keep entry components in their own files – Entry components should be in a separate file from the one that calls
ReactDOM.renderor they will be remounted on every change.
For more tips, see the official React Fast Refresh docs.
TypeScript is supported out of the box. You can reference a
.tsx file from your HTML page, and Parcel will compile it as you'd expect.
To add TypeScript definitions for React, install the following packages into your project:
yarn add @types/react @types/react-dom --dev
See the TypeScript docs for more details on using TypeScript with Parcel.
Flow is supported automatically when it is installed. To add it to an existing project, first install
flow-bin as a dependency:
yarn add flow-bin --dev
Then, use the
// @flow directive at the top of the files you'd like to type check. This also signals to Parcel which files can have Flow types that should be stripped when compiling for the browser.
See the Flow docs for more details on using Flow with Parcel.
Parcel supports many different ways of styling applications written with React.
You can also load CSS using a standard
<link rel="stylesheet"> element in your HTML file, but referencing CSS from your components helps make it clear which components depend on which CSS. This can also help with code splitting because only the CSS necessary for the components that you render will be loaded.
Parcel also supports CSS languages like SASS, Less, and Stylus. See CSS for more details on how CSS is processed by Parcel.
To use CSS modules, create a file with the
See CSS modules to learn more about how Parcel handles CSS modules.
CSS-in-JS libraries like Styled Components, Emotion, and many others work well with Parcel. Some may require build configuration, such as a Babel plugin. To enable it, create a Babel configuration in your project and Parcel will pick it up automatically.
For example, to use Emotion, install the Babel plugin and create a
.babelrc in your project:
yarn add @emotion/babel-plugin --dev
yarn add @emotion/react
You’ll also need to set the
jsxImportSource option in a
jsconfig.json so that Emotion's JSX pragma is used instead of the default one. This enables the
css prop to work.
Now, you can render elements with CSS-in-JS:
Tailwind CSS is a popular utility-first CSS framework. It uses PostCSS to build a CSS file containing only the classes you use in your code.
To use it, first, install the necessary dependencies:
yarn add tailwindcss postcss autoprefixer --dev
Next, create the config files needed for PostCSS and Tailwind. This example will use Tailwind’s JIT mode to speed up builds by only compiling the classes you use. Make sure you modify the glob passed to the
purge option so it matches all of the source files where you'll use Tailwind classes.
Finally, you can reference Tailwind classes from any files that match the
purge glob listed in
You can reference external images from JSX using the
URL constructor. Parcel also supports using query parameters to resize and convert images to a different format. It also handles image optimization, and includes a content hash in output filenames for long term browser caching.
External SVG files can be referenced as described above. You can also import SVGs as React components which can be rendered directly in JSX.
First, install the
@parcel/transformer-svg-react plugin and add it to your
yarn add @parcel/transformer-svg-react --dev
Now, you can import SVGs from your component files and render them just like any other component.
The above example showed how to convert every SVG file to JSX, but you may want to be more selective in some cases. See Importing as a React component in the SVG docs for more details.
See the SVG docs for more about how Parcel transforms and optimizes SVG files.
Code splitting helps reduce initial page load size by lazily loading sections of your app. This can be accomplished by using the dynamic
import() syntax, along with
This example lazily loads a
Profile component when a user clicks a button. When it sees the dynamic
import(), Parcel moves the
Profile component into a separate bundle from the
Home component and loads it on demand.
React.lazy handles turning this into a component, and
Suspense handles rendering a fallback while it is loading.
See the Code Splitting docs for more details about code splitting in Parcel, and Code Splitting in the React docs for more about