Start a new project
Learn how to bootstrap a new JopiJS project from scratch.
Overview
In this guide, we will walk you through the process of setting up a new JopiJS project. By the end of this tutorial, you will have:
- Installed a new project using a template.
- Installed the necessary dependencies.
- Started the development server with hot-reload.
- Learned how to run the project in different modes.
1. Prerequisites
Before we begin, ensure you have a compatible runtime installed. JopiJS works with both Bun.js and Node.js, but we highly recommend Bun.js for the best performance.
| Runtime | Requirement | Recommended? |
|---|---|---|
| Bun.js | v1.3 or later | ✅ Yes (Faster & Optimized) |
| Node.js | v24.11 or later | ⚠️ Supported |
2. Create the Project
JopiJS provides a handy CLI tool to bootstrap projects quickly. Open your terminal and run the following command to start the interactive setup:
npx jopi init --template minimalThis command will install the minimal template. If you remove the --template option, it will prompt you to select a starter template.
For beginners, we recommend choosing the minimal template. It provides a simple foundation with a single page, perfect for understanding the basics without distractions.
3. Install Dependencies
Once the project folder is created, navigate into it and install the required dependencies:
cd your-project-name
npm install && npm installNote: You may need to run npm install twice to ensure all dependencies are installed.
4. Run the Development Server
Now you are ready to start coding! JopiJS offers a powerful development mode with Hot Reload, meaning your browser will automatically update whenever you save a file.
Choose the command matching your runtime:
npm run start:ui-devOpen your browser and visit http://localhost:3000 to see your app running.
Why use this mode?
- Instant Feedback: Changes in your UI code appear instantly in the browser.
- State Preservation: (Bun only) JopiJS tries to keep your React state intact between refreshes, so you don't lose your place.
Chrome Issue: In rare cases with recent chrome versions, hot-reload might cause an infinite loop due to browser caching/SSE issues. This should be fixed, but if you encounter it, please let us know.
5. Other Running Modes
While ui-dev is best for frontend work, you might need other modes depending on what you are building.
Server Watch Mode
If you are working primarily on backend logic (API routes, server scripts) and need the server to restart automatically on every file change:
npm run start:server-devProduction Mode
To preview how your application will run in a production environment (without hot-reload or watchers):
npm run start6. Advanced Startup Flags
You can customize the startup behavior using environment variables. This is useful if you want to create custom launch scripts or fine-tune the development environment.
| Variable | Value | Description |
|---|---|---|
JOPI_DEV_SERVER | 1 | Activates the development server mode (restarts server on file change). |
JOPI_DEV_UI | 1 | Activates the Development UI (DevTools) in the browser. |
JOPI_DEV_HMR | 1 | Activates React Hot Module Replacement (HMR). Only supported on Bun.js. |
Example
To run the server with server automatic restart:
JOPI_DEV_SERVER=1 bun startAbout React HMR
Hot Module Replacement (HMR) is a game-changer for UI development. Unlike a full page reload, HMR swaps only the changed modules (components) while keeping the application running.
Why is it essential for visuals? When you are fine-tuning a design (e.g., adjusting a modal's padding or an animation timing), a standard reload would reset the page state, closing the modal or resetting the animation. With HMR, the state is preserved. You can tweak your CSS or JSX and see the results instantly without losing your context (open menus, form inputs, scroll position, etc.), enabling a much faster iteration loop.