How to Create a New PI Desktop Project: A Step-by-Step Guide

To create a new PI Desktop project, clone the repository, install dependencies with pnpm install, run the scaffolding script at scripts/create-project.mjs, and launch your workspace using pnpm --filter <project-name> dev.

PI Desktop is a multi-workspace Electron application managed as a pnpm monorepo. Creating a new project leverages the repository's built-in scaffolding tools to generate a workspace complete with configuration files, entry points, and build scripts located in examples/fixtures/.

Prerequisites

Before creating a new project, ensure your environment meets the following requirements:

• Node.js version 18 or higher
• pnpm version 8 or higher (required for workspace management)
• Rust toolchain (necessary for building the host-core crate)

Cloning the Repository and Installing Dependencies

Start by cloning the PI Desktop repository and installing JavaScript dependencies across the monorepo.

git clone https://github.com/vastsa/PI-Desktop.git
cd PI-Desktop
pnpm install

The pnpm install command resolves dependencies defined in the top-level pnpm-workspace.yaml and links every package under packages/* and apps/*.

Scaffolding a New PI Desktop Project

The repository includes a helper script that automates project creation. Run it from the repository root:

pnpm exec ts-node scripts/create-project.mjs <your-project-name>

Replace <your-project-name> with your desired workspace identifier.

What the Script Does

According to the source code in scripts/create-project.mjs, the scaffolding process performs three critical actions:

1. Directory Creation: Creates a folder at examples/fixtures/<your-project-name> containing a minimal package.json, a src/ directory, and a pi-desktop.config.ts file.
2. Workspace Registration: Adds the new directory to the monorepo's pnpm-workspace.yaml configuration, enabling the project to be built and run with the same tools as the core application.
3. Template Population: Populates the src/ entry point with a basic "Hello, PI!" component to verify the setup.

Running and Building Your Project

Once scaffolded, manage your project using pnpm's filter commands.

Development Mode

Launch the Electron host with your new project as the active workspace:

pnpm --filter <your-project-name> dev

This command invokes the dev script defined in the generated package.json, which internally forwards to the dev-electron.mjs runner located at scripts/dev-electron.mjs. The runner launches Electron with hot-reload enabled for rapid iteration.

Production Builds

Package your application for distribution:

pnpm --filter <your-project-name> build

This invokes the production bundler (Vite/Electron-builder) and produces platform-specific binaries in dist/.

Project Structure and Key Files

Understanding the generated structure helps you extend the project with custom plugins and UI components.

File Path	Purpose
scripts/create-project.mjs	Scaffolds new project skeletons and updates workspace configuration.
scripts/dev-electron.mjs	Launches the Electron host for a given workspace in development mode.
pnpm-workspace.yaml	Declares monorepo packages and projects, enabling pnpm --filter functionality.
examples/fixtures/sample-project/README.md	Documents the standard structure of generated projects.
packages/shared/README.md	Describes shared UI utilities available to new projects.
apps/desktop/README.md	Details the core desktop application that loads workspace projects.

Adding Custom UI Components

Extend your project by creating components in the src/ directory. For example, create src/main-ui.tsx:

import { Box } from "@pi-desktop/ui";

export function MainUI() {
  return <Box>Hello, PI Desktop!</Box>;
}

Register the component in your pi-desktop.config.ts:

import { MainUI } from "./src/main-ui";

export default {
  entry: MainUI,
};

Summary

• PI Desktop uses a pnpm monorepo structure requiring Node ≥18, pnpm ≥8, and Rust.
• Create projects using pnpm exec ts-node scripts/create-project.mjs <name>, which places them in examples/fixtures/.
• The scaffolding script automatically updates pnpm-workspace.yaml to include your new project.
• Run development servers with pnpm --filter <name> dev and build production binaries with pnpm --filter <name> build.
• Key implementation files include scripts/create-project.mjs for scaffolding and scripts/dev-electron.mjs for runtime management.

Frequently Asked Questions

What are the system requirements for PI Desktop development?

You need Node.js 18 or higher, pnpm 8 or higher, and a Rust toolchain for compiling the host-core crate. These dependencies support the Electron monorepo architecture and the workspace-based project structure.

Where does the create-project.mjs script place new projects?

The script creates new projects in the examples/fixtures/<project-name> directory. It also automatically registers the path in pnpm-workspace.yaml, ensuring the project is recognized as a valid workspace member.

Can I use npm or yarn instead of pnpm?

No. PI Desktop relies on pnpm workspaces as defined in pnpm-workspace.yaml. The scripts/create-project.mjs utility specifically updates this configuration file, and the build system depends on pnpm's --filter syntax for running commands across the monorepo.

How do I add custom UI components to my PI Desktop project?

Create TypeScript React components in your project's src/ directory, import them into pi-desktop.config.ts, and export them as the entry point. The scaffolding template automatically configures the build system to bundle these components into the Electron application.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}