Welcome to the Parcel Tutorial
Parcel is a modern build tool that helps developers prepare web application files for development and production. It can work with HTML, CSS, JavaScript, TypeScript, JSX, images, fonts and other assets.
This guide explains Parcel in simple English. You will learn what it does, how to install it, how to start a project, how to use npm scripts and how to create a production build.
Skill level: Beginner to intermediate.
Table of Contents
- What Is Parcel?
- How Parcel Works
- Main Features
- Requirements
- Installing Parcel
- Create Your First Project
- HTML Entry Files
- JavaScript Modules
- Working with CSS
- Images and Assets
- npm Scripts
- TypeScript
- React and JSX
- Development Server
- Production Builds
- Production Optimization
- Browser Targets
- Configuration and Plugins
- Web Workers
- Parcel Comparisons
- Common Problems
- Security Best Practices
- Practice Project
- Frequently Asked Questions
- Official Resources
1. What Is Parcel?
Parcel is a web application bundler. It takes your source files, follows their dependencies, processes supported file types and generates output files for your application.
For example, your website might contain an HTML page, several JavaScript files, a CSS stylesheet and multiple images. Parcel can process these files and prepare the necessary output for the browser.
Is Parcel a programming language?
No. JavaScript, TypeScript, HTML and CSS are technologies used to create websites. Parcel is a tool that helps process and bundle project files.
Is Parcel a framework?
No. Parcel is not a user interface framework like React. It can be used with React and other frontend technologies.
2. How Does Parcel Work?
Parcel starts from an entry file, such as index.html. It examines the files referenced by that entry and follows their dependencies.
- You create HTML, CSS, JavaScript and other source files.
- You run a Parcel command.
- Parcel discovers and processes the dependencies it supports.
- During development, Parcel serves your project and watches for changes.
- For production, Parcel generates optimized output files.
- You deploy the output files to a suitable hosting service.
3. Main Features of Parcel
- Zero-configuration approach: many common projects can start without a large configuration file.
- Development server: serve your application locally while building it.
- Automatic dependency discovery: follow imports and supported asset references.
- JavaScript and CSS processing: bundle application code and styles.
- TypeScript and JSX support: process commonly used frontend source formats.
- Asset processing: handle images, fonts and other supported resources.
- Hot module replacement: update supported modules during development.
- Code splitting: separate suitable parts of an application into different bundles.
- Tree shaking: remove eligible unused code.
- Minification: reduce production file sizes.
- Content hashing: create content-dependent asset filenames.
- Extensibility: customize the build pipeline using supported plugins.
Available features can depend on the file type, project configuration, installed packages and Parcel version.
4. What Do You Need Before Using Parcel?
To use Parcel in a normal project, you should have:
- Basic knowledge of HTML and CSS.
- Some JavaScript knowledge.
- Node.js installed in your development environment.
- npm, which is normally included with Node.js.
- A code editor or a compatible online development environment.
Check your installed versions by running these commands in a terminal:
node --version
npm --version
5. Installing Parcel
For a typical project, install Parcel as a development dependency using npm:
npm install --save-dev parcel
This command downloads Parcel and records it in your project's package.json file.
What does --save-dev mean?
The --save-dev option records the package as a development dependency. Parcel is generally needed to build your application, rather than to run the finished static website in a visitor's browser.
What is npx?
npx can run an executable provided by a package, including a locally installed package executable. In a project with Parcel installed, you can use:
npx parcel --version
Using the project-local version helps keep the build tool consistent with the project's dependencies.
6. Create Your First Parcel Project
Follow these steps in a terminal where Node.js and npm are available.
Step 1: Create a project folder
mkdir parcel-project
cd parcel-project
Step 2: Create package.json
npm init -y
This creates a basic package manifest for the project.
Step 3: Install Parcel
npm install --save-dev parcel
Step 4: Create the entry files
Create the following files in the project folder:
parcel-project/
├── index.html
├── index.js
├── style.css
├── package.json
└── node_modules/
The node_modules folder is created by npm when packages are installed. Do not normally edit its contents manually.
7. Create the HTML Entry File
Create a file named index.html and add the following code:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport"
content="width=device-width, initial-scale=1.0">
<title>My Parcel App</title>
<link rel="stylesheet" href="./style.css">
<script type="module" src="./index.js"></script>
</head>
<body>
<main>
<h1 id="heading">Hello, Parcel!</h1>
<p>My first Parcel project is running.</p>
<button id="change-button">Change heading</button>
</main>
</body>
</html>
The HTML page references both the stylesheet and JavaScript module. Parcel can follow these references when it processes the entry file.
8. Add JavaScript
Create index.js and add:
const heading = document.querySelector("#heading");
const button = document.querySelector("#change-button");
button.addEventListener("click", () => {
heading.textContent = "Parcel is working!";
});
console.log("Hello from Parcel!");
This example finds the heading and button on the page. When the visitor presses the button, JavaScript changes the heading text.
Understanding JavaScript modules
JavaScript modules allow code to be divided into separate files. A module can export functions or values for another module to import.
Create a file named math.js:
export function add(a, b) {
return a + b;
}
export function multiply(a, b) {
return a * b;
}
Then import the function in another JavaScript module:
import { add } from "./math.js";
console.log(add(10, 20));
Parcel follows supported module imports and includes the necessary code in the build output.
9. Working with CSS
Create style.css:
body {
margin: 0;
padding: 30px;
font-family: Arial, sans-serif;
background: #f4f7fb;
color: #222;
}
main {
max-width: 700px;
margin: 30px auto;
padding: 25px;
background: white;
border-radius: 12px;
}
h1 {
color: #0d47a1;
}
button {
padding: 10px 16px;
border: none;
border-radius: 6px;
background: #0d47a1;
color: white;
cursor: pointer;
}
Because index.html links to style.css, Parcel can discover the stylesheet as part of the build.
10. Images, Fonts and Other Assets
Web projects often contain more than source code. Common assets include:
- JPEG, PNG, WebP and other supported image files.
- SVG graphics and icons.
- Web fonts.
- JSON data.
- Audio and video files.
- Additional CSS and JavaScript modules.
Using an image in HTML
For an image in your project, you can write:
<img src="./images/logo.png"
alt="My application logo"
width="160">
Parcel can process supported asset references when they are part of the entry dependency graph.
Importing an image from JavaScript
In a project configured to use Parcel's standard asset processing, you can use a URL import:
import logoUrl from "./images/logo.png";
const image = document.createElement("img");
image.src = logoUrl;
image.alt = "Application logo";
document.body.appendChild(image);
Keep the referenced file at the path used in the import. The path is relative to the JavaScript file containing the import.
Using fonts
You can reference a local font from CSS:
@font-face {
font-family: "MyFont";
src: url("./fonts/my-font.woff2") format("woff2");
font-display: swap;
}
body {
font-family: "MyFont", Arial, sans-serif;
}
11. Using npm Scripts
Instead of typing the full Parcel command each time, you can define scripts in package.json.
Add or update the scripts section to look like this:
{
"scripts": {
"dev": "parcel index.html",
"build": "parcel build index.html"
},
"devDependencies": {
"parcel": "^2.0.0"
}
}
Once the scripts are saved, run the development server with:
npm run dev
For a production build, run:
npm run build
npm runs scripts using the executables installed in the project's dependencies.
12. Using TypeScript with Parcel
TypeScript adds a type system to JavaScript. Parcel supports processing TypeScript files in common project workflows.
Create index.ts:
const username: string = "TechLearn Hub";
const lessonCount: number = 25;
function greet(name: string): string {
return `Welcome, ${name}!`;
}
console.log(greet(username));
console.log("Lessons:", lessonCount);
To use this entry, change the script reference in your HTML to ./index.ts, then run Parcel with that HTML entry.
tsc --noEmit using an appropriate TypeScript configuration.
TypeScript is optional. Beginners can first learn Parcel with plain JavaScript.
13. Using React and JSX
React is a library for building user interfaces. Parcel can be used as the build tool for a React application.
For a new React project, install the packages:
npm install react react-dom
npm install --save-dev parcel
For a simple JSX example, create src.jsx:
import { createRoot } from "react-dom/client";
function App() {
return (
<main>
<h1>Hello from React and Parcel!</h1>
<p>This is a simple component.</p>
</main>
);
}
const root = createRoot(document.getElementById("root"));
root.render(<App />);
Make an HTML entry file that includes an element with the ID root and references the JSX file:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>React with Parcel</title>
<script type="module" src="./src.jsx"></script>
</head>
<body>
<div id="root"></div>
</body>
</html>
Start Parcel using the HTML entry file:
npx parcel index.html
Parcel processes the JSX as part of the build. React provides the user interface functionality; Parcel provides the build workflow.
14. Starting the Development Server
Run this command from your project directory:
npx parcel index.html
Parcel starts a development server and prints a local URL in the terminal. A common default is:
http://localhost:1234
Use the exact URL shown in your terminal if it differs from this example.
Hot module replacement
Parcel can update supported modules while the development server is running. This helps you see changes without manually rebuilding after every edit.
Some changes may still cause a full page reload. Hot updates depend on the module type and application code.
HTTPS during development
Parcel supports HTTPS development mode:
npx parcel index.html --https
Use this when you need to test browser features that require a secure context. Follow the terminal output and certificate instructions for your environment.
15. Creating a Production Build
When your application is ready to publish, run:
npx parcel build index.html
Or, if you created the npm script described earlier:
npm run build
Parcel generates production output in its distribution directory, commonly named dist.
For example, your project may look like this after building:
parcel-project/
├── index.html
├── index.js
├── style.css
├── package.json
├── node_modules/
└── dist/
├── index.html
├── index.js
└── ...generated assets
The exact filenames and folder contents depend on the project and Parcel configuration.
16. Production Optimization
Parcel can apply multiple optimizations during production builds. These can improve loading performance and reduce the amount of code or data browsers need to download.
Tree shaking
Tree shaking removes eligible code that is not used by the final application.
export function add(a, b) {
return a + b;
}
export function multiply(a, b) {
return a * b;
}
If an application only uses add, the production build may remove the unused multiply function when Parcel can safely determine that it is unnecessary.
Minification
Minification removes unnecessary formatting and may simplify code while preserving its intended behavior. It can reduce the size of JavaScript, CSS and other supported output assets.
Code splitting
Code splitting divides suitable parts of an application into separate bundles. This can help an application avoid loading all its code at the same time.
Dynamic imports
JavaScript supports dynamic imports for loading a module when it is needed:
async function loadFeature() {
const feature = await import("./feature.js");
feature.start();
}
loadFeature();
In a supported Parcel build, dynamic imports can help create separate bundles for deferred code.
Content hashing
Parcel can generate content-dependent filenames for built assets. If an asset changes, its filename can change too. This helps browsers cache unchanged assets while fetching updated ones when necessary.
Source maps
Source maps help developer tools connect generated code with the original source files. They can make debugging easier, although you should decide carefully whether production source maps should be publicly accessible.
17. Browser Targets and Compatibility
Browsers do not all support exactly the same JavaScript and CSS features. Parcel can use project target information to determine how code should be processed.
A project can declare browser targets in its package.json. For example:
{
"browserslist": [
"> 1%",
"last 2 versions"
]
}
This is an illustrative target configuration. Choose browser targets that match the actual needs of your users and the compatibility requirements of your project.
18. Parcel Configuration and Plugins
Parcel is designed to work with little configuration for many projects. Larger projects can customize the build pipeline when necessary.
The .parcelrc file
Parcel uses .parcelrc for build pipeline configuration. A minimal example is:
{
"extends": "@parcel/config-default"
}
This example extends Parcel's default configuration. It is usually unnecessary to create this file for a basic project.
What are Parcel plugins?
Plugins extend or customize the way Parcel handles project files and build output. Common plugin roles include:
- Transformers: process source files and discover dependencies.
- Resolvers: locate dependencies.
- Namers: determine output bundle names.
- Packagers: combine assets into output bundles.
- Optimizers: optimize generated assets.
- Compressors: compress output assets.
- Reporters: provide build reports or other feedback.
Only install plugins that your project actually needs. Check the plugin's documentation and compatibility with your Parcel version.
19. Building Libraries
Parcel is not limited to building websites. It can also be used for library projects, where other developers import and use your code.
A library may need to provide output suitable for different environments. Parcel supports project targets, which can be configured through package metadata and the build setup.
Before publishing a library, test the generated output, document the supported environments and confirm that required dependencies are declared correctly.
20. Web Workers and Service Workers
Web Workers allow JavaScript to run in a separate worker context, which can be useful for work that should not block the main user interface.
In a supported Parcel project, a worker can be created using a URL relative to the current module:
const worker = new Worker(
new URL("./worker.js", import.meta.url),
{ type: "module" }
);
worker.postMessage({ task: "start" });
worker.addEventListener("message", event => {
console.log("Worker response:", event.data);
});
Create a matching worker.js file:
self.addEventListener("message", event => {
if (event.data.task === "start") {
self.postMessage("Worker is running!");
}
});
Parcel supports worker-related workflows, but the exact behavior depends on the project and supported APIs. A service worker is different from a regular Web Worker and is commonly used for caching and other browser features.
21. Parcel vs Other Build Tools
Parcel vs Webpack
| Feature | Parcel | Webpack |
|---|---|---|
| Configuration approach | Emphasizes useful defaults and low configuration | Offers extensive configuration options |
| Development workflow | Includes a development server | Commonly uses webpack-dev-server or related tooling |
| Extensibility | Supports a plugin architecture | Has a broad loader and plugin ecosystem |
| Best fit | Projects that benefit from automated defaults | Projects that need detailed control over the build |
Parcel vs Vite
Parcel and Vite both provide modern frontend development workflows. Parcel emphasizes automatic asset processing and low configuration. Vite emphasizes a fast development server and a modern build workflow, with integrations for popular frontend frameworks.
The right choice depends on the project's requirements, framework, existing tooling and the developer's preferences.
Parcel vs Rollup
Rollup is widely used for bundling JavaScript libraries and applications. Parcel provides a broader out-of-the-box asset processing workflow for many web projects. Both tools can be appropriate for library builds.
Parcel vs esbuild
esbuild focuses on very fast JavaScript and CSS bundling and transformation. Parcel provides a more integrated web development and asset-processing workflow. They have different strengths, and the best option depends on the project.
22. Common Parcel Commands
| Task | Command |
|---|---|
| Initialize a project | npm init -y |
| Install Parcel | npm install --save-dev parcel |
| Check Parcel version | npx parcel --version |
| Start development | npx parcel index.html |
| Build for production | npx parcel build index.html |
| Run a development script | npm run dev |
| Run a build script | npm run build |
Commands should be run in the correct project directory. The required entry filename must match your project.
23. Common Parcel Problems and Solutions
Problem 1: The parcel command is not found
Possible cause: Parcel is not installed in the project or the command is being run in the wrong environment.
Solution: Open the project directory and install the dependency:
npm install --save-dev parcel
Then try:
npx parcel --version
Problem 2: Cannot find the entry file
Possible cause: The filename or path is incorrect.
Solution: Confirm that index.html exists in your current project directory, or supply the correct path to your actual entry file.
Problem 3: An imported file cannot be found
Possible cause: The import path is incorrect, the file is missing or the filename's letter casing does not match.
Solution: Check the relative path and make sure the file exists. For example:
import { add } from "./math.js";
Problem 4: A package cannot be imported
Possible cause: The package has not been installed, or its import path or API is incorrect.
Solution: Install the required dependency, confirm the package name and read its documentation.
Problem 5: Changes do not appear
Possible cause: The browser is displaying cached output, the development server has stopped or an error has occurred.
Solution: Check the terminal for errors, confirm that the development server is running, and reload the page if necessary.
Problem 6: The production build fails
Possible cause: A missing dependency, syntax error, invalid configuration or incompatible plugin.
Solution: Read the first meaningful error in the terminal, correct the reported issue and run the build again.
Problem 7: The deployed website is blank
Possible cause: The hosting service is serving the wrong folder, an asset path is broken or a JavaScript error prevents rendering.
Solution:
- Confirm that the production build completes successfully.
- Deploy the generated output directory, normally
dist. - Check the browser console for JavaScript errors.
- Check that images, scripts and stylesheets load successfully.
- Confirm that the hosting configuration matches the output directory.
24. Security and Good Development Practices
- Keep Node.js and project dependencies reasonably up to date.
- Review package documentation before installing unfamiliar dependencies.
- Use trusted package sources.
- Do not commit passwords, private keys or API secrets to a public repository.
- Remember that environment variables embedded in frontend bundles may become visible to website visitors.
- Review dependency audit reports and understand the risks before applying fixes.
- Test the production build before deploying it.
- Keep backups or version control for important source files.
- Do not assume that minification makes application code secret.
25. Practice Project: Build a Small Website
Use what you have learned to build a simple personal website.
Project requirements
- Create a project folder named
my-parcel-site. - Initialize npm using
npm init -y. - Install Parcel as a development dependency.
- Create
index.html. - Create
index.js. - Create
style.css. - Add a heading, introduction and button.
- Use JavaScript to make the button change a message.
- Use CSS to make the page responsive and attractive.
- Run the development server.
- Create a production build.
- Test and deploy the generated files.
Suggested JavaScript challenge
Add a button that changes the background color of a card whenever the user clicks it.
Suggested CSS challenge
Use a responsive layout, readable text, comfortable spacing and a color scheme suitable for mobile phones.
26. A Beginner's Learning Roadmap
- Learn HTML structure and semantic elements.
- Learn CSS layouts, responsive design and styling.
- Learn JavaScript variables, functions, events and modules.
- Understand Node.js and npm.
- Learn how package.json manages project dependencies and scripts.
- Install Parcel and build a small HTML project.
- Use CSS and JavaScript imports.
- Learn the development server and hot module replacement.
- Understand production builds and output folders.
- Explore TypeScript or React if your projects need them.
- Learn about asset optimization and browser compatibility.
- Practice deploying a finished project.
Do not feel that you must learn every advanced feature at once. Start with a small working project and add features gradually.
27. Frequently Asked Questions
What is Parcel used for?
Parcel processes and bundles web application files, runs a development server and creates production output.
Is Parcel free?
Parcel is an open-source build tool. Check its official repository for the current license and project information.
Does Parcel require Node.js?
A normal Parcel development workflow uses Node.js and a package manager such as npm.
Can I use Parcel without React?
Yes. You can use Parcel with plain HTML, CSS and JavaScript.
Does Parcel support TypeScript?
Yes. Parcel can process TypeScript. Full type checking may require separate TypeScript tooling.
Does Parcel have a development server?
Yes. Parcel includes a development server that can serve your project while you work.
What is hot module replacement?
Hot module replacement allows supported code modules to update during development without always requiring a full page reload.
What is the purpose of npm scripts?
npm scripts let you save frequently used commands in package.json and run them with commands such as npm run dev.
Where does Parcel put production files?
The default production output directory is commonly named dist, although configuration can change the location.
Can I deploy a Parcel website to static hosting?
Yes, if your finished website is compatible with static hosting. Deploy the generated production files and configure the host appropriately.
Is Parcel better than Vite or Webpack?
There is no universal winner. Compare configuration needs, framework support, build requirements and the team's familiarity with each tool.
Can Parcel build an Android app directly?
Parcel builds web assets; it does not independently package them as a native Android application. A separate framework or packaging tool may be needed if you want to distribute a web application as an Android app.
28. Official Parcel Resources
Use the following resources to explore Parcel further and confirm details against the current documentation.
Parcel Official Website and Documentation Getting Started with a Web Application Parcel Production Builds Parcel Development Features Parcel Source Code on GitHub Node.js Official Website npm Official DocumentationConclusion
Parcel is a useful modern build tool for developers who want to process web application files without starting with a large amount of configuration.
It supports a wide range of common web development workflows, including HTML, CSS, JavaScript, TypeScript, JSX, assets, development serving and production builds.
The best way to learn Parcel is to create a small project, run it locally, experiment with imports and styles, and then build and deploy the finished output.