Starting a Project with Templates

To start with a new project, JopiJS provides a powerful tool to configure everything for you: jopi init. It's what we will use in this tutorial to install the minimal project template which is the starting for all project with JopiJS.

1. Launching the Assistant

Open your terminal in the empty folder where you want to create your project, then run the magic command:

npx jopi init

This command downloads the latest version of the JopiJS tools and launches an interactive configuration wizard.

2. Choosing Your Starting Point

The assistant will offer you several "Templates". This is an important choice to save time:

• minimal (Recommended for this tutorial) It's a blank canvas. JopiJS is configured, but there are no pages. It's perfect for learning how to build things yourself or for starting a highly specific project.

• demo-flore-store It's a complete flower shop. Useful for seeing an example of advanced architecture (catalog, cart, shared components).

👉 Select minimal with your keyboard arrows and press Enter.

3. Installing Dependencies

Once the files are generated, you need to install the Node.js dependencies.
Depending on your preferred package manager, run:

npm install && npm install
# or
bun install && bun install

4. Understanding the Structure

Let's look at what the assistant created for you. JopiJS uses a clear and modular structure.

my-project/
├── .agent/               <-- Contains learning rules for AI.
├── bunfig.toml           <-- Bun configuration. Do not modify!
|
├── docker-compose.yml    <-- If you want to use Docker.
|-- start.sh              <-- Startup script for Docker.
|
|-- .env.development      <-- Environment variables configuration (development mode).
|-- .env.production       <-- Environment variables configuration (production mode).
|-- logConfig.json        <-- Log level configuration.
|
├── package.json          <-- Node.js dependencies and scripts.
├── node_modules/         <-- Contains installed dependencies (our npm install).
|
├── public/               <-- Where to put your downloadable files.
├── src/                  <-- Contains the application source code.
    └── mod_jopijs@uicore/          <-- The core module for JopiJS and UI.
    └── index.ts                    <-- Application entry point.

Key takeaway: You will work 99% of the time in the source folder.

5. Creating Your First Page

Currently, your site is empty. Let's create our workspace!

First, create the src/mod_app/@routes/ folder. Then, inside it, create a file named page.tsx.

Copy this code into it:

import { usePageTitle } from "jopijs/ui";

export default function HomePage() {
    // Sets the title in the browser tab
    usePageTitle("My First Project");

    return (
        <h1 className="text-5xl font-extrabold text-blue-600 mb-6">
            Hello JopiJS!
        </h1>
    );
}

🖌️ Tailwind CSS Utility Classes: You noticed strange classes like text-5xl or bg-slate-50? This is Tailwind CSS, a design tool natively integrated into JopiJS. It allows you to style your site directly in the HTML without juggling external CSS files. It is fast, maintainable, and standard.

6. Launching the Development Server

To see the result, let's start the server. Use the "dev server" command which will watch your files and automatically reload the page with every change.

npm run start:dev_server
# or
bun run start:dev_server

Open your browser at http://localhost:3000. You should see your homepage! 🎉