Getting Started

LLM Optimized

These docs are optimized for AI. Add https://buildcosmo.com/llms-full.txt to your AI IDE (like Cursor or Windsurf) for context-aware coding assistance.

Cosmo allows you to build desktop widgets using standard web technologies. This guide covers the end-to-end workflow for developing a widget using the Vite-based scaffolding tool.

Prerequisites

Node.js 20+: Required for the build tooling.
Cosmo for macOS: Must be installed and running on the same machine.
Developer Mode: Enable this in Cosmo via Settings → General. The app will ignore local development widgets if this is disabled.

Scaffold a Project

Run the create command to generate a new widget project. This initializes a Vite project configured for Cosmo.

npm create cosmo-widget@latest my-widget
cd my-widget
npm install

pnpm create cosmo-widget@latest my-widget
cd my-widget
pnpm install

yarn create cosmo-widget@latest my-widget
cd my-widget
yarn install

Setting up an existing web project? See Manual Setup to convert your project into a Cosmo widget.

Project Structure

The scaffolded project includes the following key files:

File	Purpose
`src/widget.js`	The entry point. Must export a `widget()` function.
`widget.config.json`	Mandatory configuration (dimensions, constraints, etc.). Validated at build time.
`widget.preferences-template.json`	Optional schema for user-configurable preferences shown in the widget's context menu.
`thumbnail.png`	Optional preview image for the Cosmo marketplace. Recommended resolution: 512x512px+.

Development Workflow

Start the development server to preview your widget in Cosmo.

npm run dev

This command:

Starts the local Vite development server.
Opens your widget in the Cosmo desktop app.

Server-Only Mode

To run the Vite server without opening the widget in Cosmo (useful for UI testing in a browser):

npm run dev -- -s

Build for Distribution

Package your widget for release.

npm run build

The build process:

Bundles your assets using Vite.
Validates widget.config.json against the schema.
Copies configuration files and the thumbnail to the dist/ directory.

Ensure widget.config.json is valid; build errors will occur if required fields are missing or out of bounds.

Note: Distribution through the Cosmo Marketplace is currently unavailable. Support for publishing widgets will be available soon. See Distribution for more details.

Next Steps

Configure your widget's behavior in widget.config.json.
Define user preferences in widget.preferences-template.json.
Explore the Core SDK for available APIs.

Join our Community

Connect with other developers and get support on our Discord server.

On this page