Development guide

This guide covers everything you need to contribute to ProzillaOS or create your own virtual operating system. For instructions on deploying the project to a server, see the Self-hosting guide.

Prerequisites

• Node.js v22 or higher (download)
• pnpm 11 (download)
• Git (download)

Getting started

# Clone the repository
git clone https://github.com/prozilla-os/ProzillaOS.git
cd ProzillaOS

# Install dependencies
pnpm install

# Start the demo development server
pnpm start

After starting the development server, the demo website will be available at localhost:3000.

Project structure

ProzillaOS is a monorepo managed with pnpm workspaces. See packages/README.md for a full overview of the package structure.

Tech stack

• Vite - Building packages and websites
• TypeScript - Type safety
• React - UI
• ESLint - Code linting
• pnpm - Package management
• VitePress - Documentation
• Vitest - Testing

Commands

Command	Description
pnpm build	Build all packages, demo and docs
pnpm packages:build	Build only packages (not websites)
pnpm start	Start the demo development server
pnpm lint	Lint all files with ESLint (auto-fix)
pnpm test	Run all tests with Vitest
pnpm clean	Remove all build artifacts
pnpm demo:start	Start the demo development server
pnpm demo:build	Build the demo website for production
pnpm docs:start	Start the docs development server
pnpm docs:build	Build the docs website for production
pnpm docs:api	Generate API reference docs via TypeDoc
pnpm docs:api:libs	Generate API docs for libraries only
pnpm docs:api:apps	Generate API docs for apps only

NOTE

The pnpm build command runs builds sequentially across all packages and websites. If you only need to rebuild packages, use pnpm packages:build. The docs website requires packages to be built first (this happens automatically via pnpm docs:build's prebuild step).

Code style

Most conventions are enforced by ESLint. ESLint is configured with TypeScript-aware rules. Run pnpm lint to check and auto-fix all files. The configuration is in eslint.config.js at the project root.

Naming conventions

Category	Case	Example	Name should match
Folders	kebab-case	virtual-drive
.ts files	camelCase	virtualRoot.ts
.tsx files	PascalCase	Desktop.tsx	React component
.css files & static assets	kebab-case	global.css
Local .module.css files	PascalCase	Desktop.module.css	React component
Global .module.css files	kebab-case	utils.module.css
CSS class names	PascalCase	.WindowsView	React component
Variables	camelCase	const fooBar = true;
Global constant variables	MACRO_CASE	export const NAME = "ProzillaOS";
Classes	PascalCase	class WindowsManager { }
React components	PascalCase	export function WindowsView({ }) { }
Functions	camelCase	function focusWindow() { }
Types	PascalCase	type FooBar = boolean;

Other conventions

• Indentation: Tabs
• Quotes: Double quotes
• Semicolons: Required
• Imports: Use type prefix for type-only imports (import type { Foo } from "...")
• React components: One component per file, no other exports
• JSDoc: Checked by eslint-plugin-jsdoc, complete sentences and hyphens before parameter descriptions

Branching

• feat/feature-name - New features
• fix/bug-description - Bug fixes
• release - Release preparation

Commits

Commit messages use descriptive English sentences. An optional scope prefix (the package name) can be used for clarity. The scope of the package itself (e.g., @prozilla-os/) is omitted for brevity. Commit message subjects should be at most 50 characters long, unless that is not enough to cover all the changes, in which case it might be worth considering splitting up your commit.

Examples

core: Added virtual drive support
demo: Updated wordle
Fixed build error
Refactored shell + updated documentation

Pull requests

• PRs should target the main branch
• The title should clearly describe the change
• Keep PRs focused on a single concern when possible

Testing

Tests use Vitest. Run pnpm test to execute all test suites across the monorepo.

pnpm test

Documentation

The documentation is built with VitePress and lives in the docs/ directory.

Running locally

pnpm docs:start

The documentation website will be available at localhost:3000/docs.

API reference

The API reference pages under docs/src/reference/ are auto-generated by TypeDoc using typedoc-plugin-markdown. To regenerate them:

pnpm docs:api # All packages
pnpm docs:api:libs # Libraries only (core, shared, skins, dev-tools)
pnpm docs:api:apps # Applications only

API reference generation runs automatically before pnpm docs:build.

Navigation

The docs sidebar is configured in docs/.vitepress/nav.config.ts. Package reference items are generated dynamically from packages.config.ts.

Releasing packages

See the Self-hosting guide for instructions on publishing packages to npm.

Support

If you have questions or need help, reach out to the community on Discord.