Project Overview

To create a cross-platform desktop application, you need to create a MōBrowser project. It contains all the files and dependencies required to build and run your desktop application.

Creating a Project 

Make sure your current working directory is the one where you intend to create a project. Run the following command in your command line:

npm create mobrowser-app@latest

This command will install and execute create-mobrowser-app, the official project scaffolding tool. It asks for:

1. The project name.
2. Whether to add a native module to access platform-specific APIs. The native module can be written in C++ or Rust.
3. Whether to initialize a Git repository in the project directory.

✔ Project name: App
✔ Add a native module? No
✔ Initialize a Git repository? Yes

The tool then creates the project in a new directory, installs its dependencies, and runs code generation, so the project is ready to run with npm run dev.

Project template 

Every project is created from the same template: a React and TypeScript app with shadcn/ui components. It’s a small working desktop app that you can build on:

• A “Hello, world!” main window with a hidden title bar.
• An application menu with File, Edit, View, and Window menus (Help on Windows).
• A Settings window with a theme picker, launch at login, automatic update checks, and an About page.
• Links that open external URLs in the default browser.
• The shadcn app kit: Base UI components and ready-made patterns such as pages, a router, a search field, faceted filters, a data table, a confirmation dialog, and a save bar.
• End-to-end tests for the main window and the Settings window, and GitHub Actions workflows that run them and release the app.

The project is ready for development with an AI coding agent. AGENTS.md, mirrored by CLAUDE.md, explains to the agent how to run, inspect, and test the app. The .agents/skills/ directory contains skills with rules the agent follows:

Git repository 

When you run the tool outside a Git repository, it asks whether to initialize a Git repository in the new project directory, and runs git init by default. The question is skipped if Git isn’t installed. If git init fails, the tool warns you and keeps the project.

You can also create a repository first, for example on GitHub, clone it, and create the project inside the clone:

gh repo create my-app --private --clone --add-readme
cd my-app
npm create mobrowser-app@latest

When the current directory is the root of a Git repository that has only a README, the tool asks where to create the project:

? This directory is a Git repository root. Generate the project here? (Use arrow keys)
❯ Yes
  No, in a subdirectory

With Yes, the project is created at the repository root, next to the README, and the project name defaults to the name of the directory. The generated GitHub Actions workflows are then at the root of the repository, where GitHub runs them. If the repository has other files, the project is created in a subdirectory without asking.

Opening the project in a coding agent or IDE 

When the project is ready, the tool lists the coding agents and IDEs installed on your machine and offers to open the project in one of them:

? Open it in a coding agent/IDE: (Use arrow keys)
❯ ChatGPT Desktop (Codex)
  Claude Code
  Claude Desktop
  Codex
  Cursor
  VS Code
  No

Only the tools found on your machine are listed:

For example, for Claude Code:

To open the project in Claude Code, run:
  cd App
  claude

Choose No to see how to run the app instead. The tool doesn’t ask this question when no coding agent or IDE is found, or when it runs without an interactive terminal.

Creating a project without prompts 

To create a project without prompts, for example in a script, pass the options on the command line:

npm create mobrowser-app@latest -- --name App --native rust --git no

Without prompts, the tool doesn’t offer to open the project in a coding agent or IDE.

Project structure 

If you add a native C++ module, you will see the following files and folders in the generated project:

.agents/
├── skills/
.github/
├── workflows/
.vscode/
assets/
resources/
src/
├── main/
├── native/
├── renderer/
test/
├── e2e/
.gitignore
AGENTS.md
CLAUDE.md
CMakeLists.txt
components.json
mobrowser.conf.json
package.json
playwright.config.ts
postcss.config.js
tsconfig.json
tsconfig.node.json
vite.config.ts

Here is the description of the files and folders in the project structure:

A project without a native module has no src/native/ and CMakeLists.txt.

A project with a native Rust module has Cargo.toml, Cargo.lock, build.rs, and rust-toolchain.toml instead of CMakeLists.txt. See Native Rust Module.

Project configuration 

The mobrowser.conf.json file is the main project and application configuration file. It contains the application name, version, author, copyright, description, and other properties.

Here’s an example of the mobrowser.conf.json file:

{
  "app": {
    "name": "Stats",
    "version": {
      "major": "1",
      "minor": "0",
      "patch": "0"
    },
    "author": "TeamDev",
    "copyright": "Copyright © 2026 TeamDev",
    "description": "System resources monitor and process explorer.",
    "locales": ["en-US"],
    "trustedOrigins": [],
    "schemes": [],
    "updateServerUrl": "",
    "bundle": {
      "macOS": {
        "icon": "assets/app.icns",
        "executableName": "Stats",
        "bundleID": "com.teamdev.Stats",
        "codesignIdentity": "${MACOS_CODESIGN_IDENTITY}",
        "codesignKeychain": "${KEYCHAIN_PATH}",
        "codesignEntitlements": "assets/entitlements.plist",
        "teamID": "${MACOS_TEAM_ID}",
        "appleID": "${MACOS_APPLE_ID}",
        "password": "${MACOS_APPLE_PASSWORD}",
        "extraInfo": "",
        "installer": {
          "dmg": {
            "name": "",
            "volumeName": "",
            "volumeIcon": "assets/app.icns",
            "eula": "",
            "deltaStrategy": "BestSize",
            "window": {
              "textSize": 14,
              "skipPrettifying": false,
              "backgroundImage": "",
              "position": {
                "x": 500,
                "y": 400
              },
              "size": {
                "width": 600,
                "height": 400
              },
              "icon": {
                "size": 150,
                "position": {
                  "x": 160,
                  "y": 160
                }
              },
              "appDropLink": {
                "x": 430,
                "y": 160
              }
            }
          }
        }
      },
      "Windows": {
        "icon": "assets/app.ico",
        "executableName": "Stats",
        "signCommand": "",
        "installer": {
          "exe": {
            "name": "",
            "icon": "assets/app.ico",
            "installationGif": "",
            "packageId": "Stats",
            "installationFolderName": "Stats",
            "displayName": "Stats",
            "shortcuts": "Desktop,StartMenuRoot",
            "deltaStrategy": "BestSpeed"
          }
        }
      },
      "Linux": {
        "icon": "assets/app.png",
        "executableName": "Stats"
      }
    }
  }
}

Here’s the description of the properties in the mobrowser.conf.json file. Paths may be absolute or relative to the project root. You can reference environment variables in string values using the ${ENV_NAME} syntax, which is especially useful for signing credentials.

Application properties 

app.bundle.macOS properties 

app.bundle.Windows properties 

app.bundle.Linux properties 

vite.config.ts 

The framework uses Vite as the build tool for both the main and the renderer processes.

Each MōBrowser project includes a vite.config.ts file. It defines the build configuration for the main and the renderer processes.