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

> Learn to create a new PI Desktop project by cloning the repository, installing dependencies, running the scaffolding script, and launching your workspace. Get started today!

- Repository: [Lan/PI-Desktop](https://github.com/vastsa/PI-Desktop)
- Tags: how-to-guide
- Published: 2026-09-12

---

**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.

```bash
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`](https://github.com/vastsa/PI-Desktop/blob/main/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:

```bash
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`](https://github.com/vastsa/PI-Desktop/blob/main/package.json), a `src/` directory, and a [`pi-desktop.config.ts`](https://github.com/vastsa/PI-Desktop/blob/main/pi-desktop.config.ts) file.
2. **Workspace Registration**: Adds the new directory to the monorepo's [`pnpm-workspace.yaml`](https://github.com/vastsa/PI-Desktop/blob/main/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:

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

```

This command invokes the `dev` script defined in the generated [`package.json`](https://github.com/vastsa/PI-Desktop/blob/main/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:

```bash
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`](https://github.com/vastsa/PI-Desktop/blob/main/pnpm-workspace.yaml) | Declares monorepo packages and projects, enabling `pnpm --filter` functionality. |
| [`examples/fixtures/sample-project/README.md`](https://github.com/vastsa/PI-Desktop/blob/main/examples/fixtures/sample-project/README.md) | Documents the standard structure of generated projects. |
| [`packages/shared/README.md`](https://github.com/vastsa/PI-Desktop/blob/main/packages/shared/README.md) | Describes shared UI utilities available to new projects. |
| [`apps/desktop/README.md`](https://github.com/vastsa/PI-Desktop/blob/main/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`](https://github.com/vastsa/PI-Desktop/blob/main/src/main-ui.tsx):

```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`](https://github.com/vastsa/PI-Desktop/blob/main/pi-desktop.config.ts):

```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`](https://github.com/vastsa/PI-Desktop/blob/main/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`](https://github.com/vastsa/PI-Desktop/blob/main/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`](https://github.com/vastsa/PI-Desktop/blob/main/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`](https://github.com/vastsa/PI-Desktop/blob/main/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.