---
title: "Alloy"
canonical_url: https://developer.repebble.com/guides/alloy/
last_updated: 2026-10-11
sdk_version: 4.44
---
# Alloy

Source: https://developer.repebble.com/guides/alloy/

Alloy is a JavaScript framework for building Pebble apps, based on the [Moddable SDK](https://www.moddable.com/). Alloy provides developers a mix of standard Web APIs, standard Embedded JavaScript APIs from ECMA-419, and dedicated Pebble OS APIs. It allows you to write apps using modern JavaScript (ES2025, ES6++) with powerful UI frameworks and access to Pebble hardware features.

> **Platform Support** : Alloy currently supports Emery (Pebble Time 2) and Gabbro (Pebble Round 2). See the platform support table in [_Hardware Information_](https://developer.repebble.com/guides/tools-and-resources/hardware-information.md#platform-support).

## Key Features

- **Modern JavaScript** : Write apps using ES modules, classes, async/await, and other modern JavaScript features
- **Two UI Frameworks** : Choose between Piu (declarative, component-based) or Poco (procedural, low-level graphics)
- **Hardware Access** : Full access to accelerometer, battery, buttons, compass, and other Pebble sensors
- **Network Communication** : Built-in support for HTTP requests, WebSockets, and watch-phone messaging
- **Persistent Storage** : Simple APIs for storing data locally using `localStorage`, key-value storage, or files

## Getting Started

To create a new Alloy project:

```
$ pebble new-project --alloy my-app
```

This creates a new project with the standard Alloy structure:

```
my-app/
  src/
    embeddedjs/
      main.js # Watch code (runs on Pebble)
    pkjs/
      index.js # Phone code (for networking, location)
    c/
      mdbl.c # C code as entry point for embeddedjs (usually no need to modify)
  resources/ # App resources (images, fonts)
  package.json # App manifest
```

Alloy apps have two JavaScript environments: **embeddedjs** runs on the watch, while **pkjs** runs on the connected phone for network and location services.

## Hello World

The simplest Alloy app:

```
console.log("Hello, Pebble!");
```

## Rocky.js

Rocky.js is no longer part of the firmware or the SDK. Alloy replaces it.

## Guides

- [**Getting Started with Alloy**](https://developer.repebble.com/guides/alloy/getting-started.md) - Learn how to create your first Alloy app for Pebble.

- [**Piu UI Framework**](https://developer.repebble.com/guides/alloy/piu-guide.md) - Build declarative user interfaces with the Piu framework.

- [**Poco Graphics**](https://developer.repebble.com/guides/alloy/poco-guide.md) - Low-level graphics rendering with the Poco framework.

- [**Sensors and Input**](https://developer.repebble.com/guides/alloy/sensors-and-input.md) - Access Pebble sensors and handle button input in Alloy apps.

- [**Storage**](https://developer.repebble.com/guides/alloy/storage.md) - Persist data between app launches using localStorage, key-value storage, or files.

- [**Networking**](https://developer.repebble.com/guides/alloy/networking.md) - Make HTTP requests and use WebSockets via the phone proxy.

- [**App Messages**](https://developer.repebble.com/guides/alloy/app-messages.md) - Send and receive messages between the watch and the phone.

- [**Watchfaces**](https://developer.repebble.com/guides/alloy/watchfaces.md) - Build custom watchfaces with Alloy.

- [**Animations**](https://developer.repebble.com/guides/alloy/animations.md) - Create smooth animations using Timeline and easing functions.

- [**Port (Custom Drawing)**](https://developer.repebble.com/guides/alloy/port-drawing.md) - Combine Piu's declarative UI with custom drawing using Port.

- [**Advanced Networking**](https://developer.repebble.com/guides/alloy/advanced-networking.md) - Low-level HTTP and WebSocket clients for advanced networking needs.

- [**Native Functions (FFI)**](https://developer.repebble.com/guides/alloy/ffi.md) - Call native C functions directly from JavaScript in your Alloy app using the Foreign Function Interface.

- [**Dictation**](https://developer.repebble.com/guides/alloy/dictation.md) - Capture speech as text in Alloy apps using the dictation API.

- [**Wakeups**](https://developer.repebble.com/guides/alloy/wakeups.md) - Schedule your Alloy app to launch at a future time using wakeups.

- [**Vibration**](https://developer.repebble.com/guides/alloy/vibration.md) - Provide haptic feedback in Alloy apps using the vibration motor.

- [**Device Info and App Events**](https://developer.repebble.com/guides/alloy/device-info.md) - Query watch and screen properties, respond to app lifecycle events, and control the backlight in Alloy apps.

- [**Health**](https://developer.repebble.com/guides/alloy/health.md) - Read steps, sleep, activities and heart rate data from Pebble Health in Alloy apps.

- [**Alloy Reference**](https://developer.repebble.com/guides/alloy/reference.md) - Where the Alloy APIs are documented, and the details that are not obvious from the other guides: font names, resource IDs, modules, memory and TypeScript.

## Example Apps

The [Moddable Pebble Examples](https://github.com/Moddable-OpenSource/pebble-examples) repository contains a collection of examples covering all aspects of Alloy development. Here's a categorized overview:

### Fundamentals

| Example | Description |
| --- | --- |
| [hellopebble](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellopebble) | "Hello, world" - the simplest starting point |
| [hellotimer](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellotimer) | Using `setTimeout` |
| [hellomodule](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellomodule) | Loading multiple modules |
| [hellotypescript](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellotypescript) | TypeScript with the Pebble `Button` class |

### Storage

| Example | Description |
| --- | --- |
| [hellokeyvalue](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellokeyvalue) | ECMA-419 Key-Value Storage for persistent data |
| [hellolocalstorage](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellolocalstorage) | Web standard `localStorage` for persisting strings |
| [hellofiles](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellofiles) | File system storage |

### Sensors & Input

| Example | Description |
| --- | --- |
| [helloaccelerometer](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/helloaccelerometer) | Subscribing to accelerometer readings |
| [hellobattery](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellobattery) | Battery and charging status |
| [hellolocation](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellolocation) | GPS location via phone |
| [hellobutton](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellobutton) | Pebble button events |
| [hellopoco-drag](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellopoco-drag) | Touch events with the ECMA-419 touch driver |

### Piu UI Framework

| Example | Description |
| --- | --- |
| [hellopiu-text](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellopiu-text) | Dynamic text layout with different fonts |
| [hellopiu-pebbletext](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellopiu-pebbletext) | Text using Pebble built-in fonts |
| [hellopiu-balls](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellopiu-balls) | Classic bouncing balls demo |
| [hellopiu-coloredsquares](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellopiu-coloredsquares) | Drawing colored squares |
| [hellopiu-gbitmap](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellopiu-gbitmap) | Pebble GBitmap PNG images as Piu textures |
| [hellopiu-jsicon](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellopiu-jsicon) | Moddable SDK bitmaps as Piu textures |
| [hellopiu-port](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellopiu-port) | Animated graph using Piu Port |
| [hellopiu-timeline](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellopiu-timeline) | Easing equations with Timeline animation |

### Piu Watchfaces

| Example | Description |
| --- | --- |
| [cupertino](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/piu/watchfaces/cupertino) | Classic macOS watch cursor as a watchface |
| [london](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/piu/watchfaces/london) | Big Ben (color watches only) |
| [helsinki](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/piu/watchfaces/helsinki) | Minimal design with per-model assets |
| [redmond](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/piu/watchfaces/redmond) | Classic Windows clock |
| [zurich](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/piu/watchfaces/zurich) | Iconic Swiss railway clock |

### Poco Renderer

| Example | Description |
| --- | --- |
| [hellopoco-text](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellopoco-text) | Text rendering with Moddable SDK fonts |
| [hellopoco-pebbletext](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellopoco-pebbletext) | Text rendering with Pebble built-in fonts |
| [hellopoco-gbitmap](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellopoco-gbitmap) | Rendering GBitmap resources |
| [hellopoco-pebblegraphics](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellopoco-pebblegraphics) | Lines, round rectangles, and circles |
| [hellopoco-qrcode](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellopoco-qrcode) | Dynamic QR code generation |
| [hellopoco-pdc](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellopoco-pdc) | Rendering PDC (SVG) images |
| [hellopoco-pdc-rotate](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellopoco-pdc-rotate) | Spinning a PDC image |
| [hellopoco-pdc-scale](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellopoco-pdc-scale) | Animated PDC scaling with easing |
| [hellopoco-pdc-sequence](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellopoco-pdc-sequence) | PDC image sequence animation |
| [hellowatchface](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellowatchface) | Simple watchface app |

### Communication

| Example | Description |
| --- | --- |
| [hellomessage](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellomessage) | Watch-phone messaging via app\_message |
| [helloconnected](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/helloconnected) | Phone connection status notifications |
| [hellofetch](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellofetch) | HTTP requests using the `fetch()` API |
| [hellohttpclient](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellohttpclient) | HTTP requests using ECMA-419 HTTP Client |
| [hellowebsocket](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellowebsocket) | WebSocket using the Web standard API |
| [hellowebsocketclient](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellowebsocketclient) | WebSocket using ECMA-419 WebSocket Client |

### Sensor Visualizations (Piu)

| Example | Description |
| --- | --- |
| [compass](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/piu/apps/compass) | Compass visualization (Emery only) |
| [gravity](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/piu/apps/gravity) | Accelerometer visualization (Emery only) |
| [tic-tac-toe](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/piu/apps/tic-tac-toe) | Touch game using Piu Behavior touch events |

### Device, Events & Feedback

| Example | Description |
| --- | --- |
| [helloinfo](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/helloinfo) | Watch, screen, and device information |
| [helloappevents](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/helloappevents) | App focus and display resize events |
| [hellowakeup](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellowakeup) | Scheduling the app to launch later with wakeups |
| [hellodictation](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellodictation) | Capturing speech as text with dictation |
| [hellovibes](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellovibes) | Haptic feedback with the vibration motor |
| [hellolight](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/hellolight) | Controlling the backlight |

### Native Code

| Example | Description |
| --- | --- |
| [helloffi](https://github.com/Moddable-OpenSource/pebble-examples/tree/main/helloffi) | Calling native C functions from JavaScript (FFI) |

## Additional Resources

- [Moddable SDK Documentation](https://www.moddable.com/documentation/readme) - Comprehensive documentation for Piu, Poco, and other modules
