Topic: Running the React Development Server
Level: Beginner to Intermediate
Prerequisites: Basic knowledge of HTML, CSS, JavaScript, React, Node.js, npm, and React project structure.
A React development server is a local server that allows developers to run, view, test, and debug a React application during development. It serves the application's files to a web browser and helps developers see changes while working on the project.
In a typical React project created with Vite, the development server is started using the npm run dev command. Once the server starts, the terminal displays a local URL that you can open in your browser to view the application.
The development server is useful because it supports fast feedback during coding, module updates, and error reporting. Vite provides Hot Module Replacement (HMR), which can update changed modules without requiring a full page reload in many cases.
Example: When you edit App.jsx and save the file, the browser can update to show the new UI without manually restarting the server.
A development server is a tool that serves your application's files locally while you build and test your project. It is designed to support the development workflow rather than serve as the final production hosting environment.
For a typical Vite React application, the development server:
Important: A development server is intended for local development and testing. A production application should be built and deployed using an appropriate hosting or deployment setup.
Node.js is a JavaScript runtime that allows JavaScript tools and development utilities to run outside the browser. React development tools such as Vite rely on Node.js.
Download Node.js from the official Node.js website.
npm is a package manager commonly installed with Node.js. It helps developers install dependencies and run commands defined in the project's package.json file.
A code editor such as Visual Studio Code can help you create, edit, and manage React project files.
A modern browser such as Chrome, Firefox, Edge, or Safari allows you to view and test your React application.
Many modern React projects use Vite to provide the development server and build tooling. Other project setups may use different commands, so always check the project's package.json.
Before running a React project, check that Node.js and npm are available on your computer.
Open Command Prompt, PowerShell, or a terminal and execute:
node -v
npm -vThe commands display the installed versions when the tools are available.
Example output:
v22.x.x
10.x.xThe exact version numbers may differ depending on your installation.
If the commands are not recognized, install Node.js and reopen the terminal. For a new Vite project, check the current Vite documentation for the required Node.js version.
If you do not already have a React project, you can create one using Vite.
Open your terminal or command prompt in the directory where you want to create your project.
npm create vite@latest my-react-app -- --template reactThis command creates a new Vite project named my-react-app using the React template.
cd my-react-appThis command changes the terminal's current directory to your new React project.
npm installThis command installs the packages specified in the project's dependency configuration and creates or updates the local dependency installation.
npm run devVite starts its development server and prints a local URL in the terminal.
If you already have a React project, you usually do not need to create another one. Follow these steps to run the existing application.
package.json.package.json.For a typical Vite React project, use:
npm install
npm run devIf dependencies are already installed and current, you can generally run only:
npm run devImportant: If npm run dev reports that the script does not exist, open package.json and check the available scripts. Different project setups may use a different command.
The package.json file contains project metadata, dependencies, and scripts. npm uses scripts to run common project tasks.
A typical Vite React project's scripts section may look like this:
{
"scripts": {
"dev": "vite",
"build": "vite build",
"preview": "vite preview"
}
}Let's understand the purpose of each script.
| Command | Purpose |
|---|---|
npm run dev |
Starts the development server. |
npm run build |
Creates an optimized production build. |
npm run preview |
Locally previews the production build produced by Vite. |
Note: The scripts shown above are common Vite defaults. Your project may contain additional scripts or use different commands.
After running npm run dev, Vite usually displays information about the server and its local address.
Illustrative example:
VITE ready
Local: http://localhost:5173/
Network: use --host to exposeThe exact wording, port number, and output format may vary.
The local URL allows you to access the application from the same computer on which the development server is running.
The port identifies the network endpoint used by the server. Vite commonly uses port 5173 by default, but it may select another available port if that port is already occupied.
The network address option can allow other devices on your local network to access the development server when configured correctly. Exposing the server should be done carefully, especially on public or untrusted networks.
Once the server starts successfully, open the local URL printed in the terminal.
For example:
http://localhost:5173/The browser requests the application from the local development server. The HTML entry point loads the JavaScript entry file, which initializes React and renders the application's component tree.
If the starter React template is still in place, you may see the default Vite and React page. If you have edited App.jsx, the browser should display your custom interface.
Remember: Keep the terminal process running while you use the development server. Closing the terminal or stopping the process usually makes the local URL unavailable.
A typical Vite React project contains several files that work together to display the application.
my-react-app/
├── index.html
├── package.json
├── vite.config.js
└── src/
├── main.jsx
├── App.jsx
├── App.css
└── index.cssRole of each file:
index.html provides the initial HTML document and loads the JavaScript entry point.main.jsx initializes React and renders the App component into the root DOM element.App.jsx defines the main application UI.App.css contains styles used by the App component when imported.index.css commonly contains global styles.package.json lists dependencies and project scripts.vite.config.js, when present, contains Vite configuration.Application flow:
Run npm run dev
↓
Vite starts the development server
↓
Open the local URL in a browser
↓
Browser loads index.html
↓
main.jsx initializes React
↓
React renders App.jsx
↓
Application UI appears in the browserHot Module Replacement (HMR) is a development feature that allows supported modules to update in the browser without requiring a full page reload in many cases.
Vite supports HMR to make the development process faster and more convenient.
Suppose your App.jsx file contains:
function App() {
return (
<div>
<h1>Hello, React!</h1>
</div>
);
}
export default App;Change the heading to:
<h1>Welcome to My React Project!</h1>After you save the file, the browser may update the heading automatically.
Benefits of HMR:
Note: Not every change can be applied without a reload. Some changes may trigger a full page refresh, depending on the module and application setup.
Many source-code changes are picked up automatically. However, you may need to restart the server after changing certain configuration files or environment settings.
To restart the server:
Ctrl + C to stop it.npm run devTo stop the development server, press Ctrl + C in the terminal running the process. The server stops, and its local URL is no longer served by that process.
If the default port is unavailable or you want to use a different port, you can specify one on the command line.
Example:
npm run dev -- --port 3000This passes the --port 3000 option to Vite through the npm script.
You can also configure Vite to use a port in vite.config.js.
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
export default defineConfig({
plugins: [react()],
server: {
port: 3000
}
});When you use a configuration file, ensure the required Vite React plugin is installed if your configuration imports it.
Important: If a port is occupied, Vite may choose another available port by default. If you want it to fail instead of switching ports, use the --strictPort option.
npm run dev -- --port 3000 --strictPortBy default, a development server may listen only on a local interface. To access it from another device on the same network, you may need to configure the server to listen on a network interface.
Example:
npm run dev -- --host 0.0.0.0Then use the computer's reachable local network IP address and the port shown by Vite on the other device.
Safety tips:
| Error or problem | Possible cause | Solution |
|---|---|---|
npm is not recognized |
Node.js/npm is not installed or is not available in the system PATH. | Install Node.js, reopen the terminal, and check node -v and npm -v. |
| Missing dev script | package.json does not define a dev script. |
Check the scripts section and use the command supported by your project. |
vite is not found |
Dependencies have not been installed or Vite is not configured as a project dependency. | Run npm install and inspect the project dependencies. |
| Port already in use | Another process is using the requested port. | Stop the other process or start the server on another available port. |
| Blank browser page | The application may have a runtime error, a broken import, or a missing root element. | Check the browser console, terminal output, and React entry-point files. |
| Failed to resolve import | An imported file path or package name is incorrect. | Verify the filename, path, capitalization, and dependency installation. |
| Changes do not appear | The file may not have been saved, HMR may have failed, or the wrong server may be open. | Save the file, inspect terminal output, verify the URL, and restart the server if necessary. |
| Unsupported Node.js version | The installed Node.js version does not meet the tool's requirements. | Check the current Vite requirements and install a compatible Node.js version. |
| Cannot connect to localhost | The server is not running, or the URL/port is incorrect. | Restart the server and use the exact local URL printed in the terminal. |
| Network device cannot connect | The server is listening only locally, or network/firewall rules block access. | Check the host setting, local IP address, port, and firewall rules. |
If the React application does not start, follow this checklist.
node -v.npm -v.package.json.npm install if required.package.json and confirm the available commands.npm run dev for a typical Vite project.Ctrl + C and start it again.A development server and a production build serve different purposes.
| Feature | Development server | Production build |
|---|---|---|
| Purpose | Developing, testing, and debugging the application. | Preparing optimized files for deployment. |
| Typical Vite command | npm run dev |
npm run build |
| Output | Serves source modules and development features. | Generates optimized static assets, commonly in dist. |
| Hot Module Replacement | Available during development. | Not used as a development feature in the deployed build. |
| Typical usage | Local development. | Deployment to a hosting platform or web server. |
To create a production build in a Vite project, run:
npm run buildTo preview the built output locally, run:
npm run previewImportant: Vite's preview command is intended to test the production build locally. It is not a replacement for a properly configured production hosting service.
Objective: Start a React development server and verify that code changes appear in the browser.
Open your Vite React project in a code editor and launch its terminal.
npm installnpm run devCopy the local URL from the terminal and open it in your browser.
function App() {
return (
<div>
<h1>React Development Server</h1>
<p>My React application is running successfully.</p>
<button onClick={() => alert('React is working!')}>
Test Application
</button>
</div>
);
}
export default App;Save App.jsx. The browser should update to display the heading, paragraph, and button. Click the button to test its event handler.
Return to the terminal and press Ctrl + C.
Expected learning outcome: You will know how to start, access, update, test, and stop a React development server.
package.json.Answer: It is a local server that serves a React application during development and helps developers test, debug, and preview code changes in a browser.
Answer: The standard command is npm run dev, provided that the project's package.json defines a dev script.
Answer: Vite is a frontend build tool that provides a development server and build process for modern web projects, including React applications.
Answer: npm is a package manager commonly used to install project dependencies and run scripts defined in package.json.
Answer: It installs the project's dependencies based on its package configuration and lockfile, when available.
Answer: localhost refers to the local computer. A development server can use a localhost URL so the application can be accessed from the same machine.
Answer: A port identifies the network endpoint through which a server accepts connections. Vite commonly starts on port 5173, but the actual port can vary.
Answer: HMR updates supported modules in the browser during development without requiring a full page reload in many cases.
Answer: Press Ctrl + C in the terminal where the server is running.
Answer: Stop the process using the port or select another available port using an option such as npm run dev -- --port 3000.
Answer: npm run dev starts the development server, while npm run build generates an optimized production build in a typical Vite project.
Answer: Common reasons include missing dependencies, an incorrect project directory, a missing script, an incompatible Node.js version, or a configuration error.
Answer: Usually not. Vite supports automatic updates and HMR for many source changes. Certain configuration changes may require restarting the server.
Answer: No. It is intended for development. Build the application and deploy the resulting assets using an appropriate production hosting setup.
npm install.npm run dev.package.json scripts.Running the React development server is an essential part of React development. It allows you to open your application locally, test your components, identify errors, and view code changes quickly. In a typical Vite React project, the main steps are to install dependencies, run npm run dev, open the displayed local URL, and keep the server running while you work.
For structured learning, visit the JustAcademy React JS Training Course.
To request more course information or a demonstration, visit Register for React JS Course Demo.
