# Overview

> Build on-device apps for smart glasses with the Glassly Miniapp SDK.

Source: https://docs.glassly.ai/app-devs/getting-started/overview/

Glassly is the operating system for smart glasses. A **miniapp** is an app that
runs on the user's phone, inside the Glassly App, and drives the glasses through the
Glassly Miniapp SDK (`@glassly/miniapp`). You write a bundle, the user installs it
from the Glassly Miniapp Store, and it runs on their device.

Building a mobile app that connects directly to glasses over Bluetooth? Use the
[Bluetooth SDK docs](https://docs.glassly.ai/bluetooth-sdk/overview.md) instead.

## How a miniapp is built

Every miniapp has two layers:

- Background: an always-on JavaScript context (no DOM) that owns all the
  glasses logic: subscribing to the microphone, drawing to the display, reacting
  to button presses. It holds your `session`.
- UI: an on-demand WebView (React + your styles) that opens when the user
  taps your miniapp's tile, and is torn down when they leave. It has no direct
  hardware access; it talks to the background layer over a typed message bus.

This split exists so dozens of miniapps can stay resident on a phone without each
one holding a heavyweight WebView in memory. See
[Two-layer architecture](https://docs.glassly.ai/app-devs/core-concepts/two-layer-architecture.md) for the
full picture.

## Hello world

This background entry shows text on the glasses when the user presses a button:

```typescript src/background/index.ts
import { registerMiniapp } from "@glassly/miniapp/background";

registerMiniapp((session) => {
  // Runs once the miniapp connects. `session` is your handle to the glasses.
  // display.render() replaces the frame; a stable id updates the element in
  // place. Boxes are raw device px, see session.capabilities.display.
  const hud = { x: 0, y: 0, w: 576, h: 288 };
  session.input.onButtonPress(() => {
    session.display.render([{ type: "text", id: "hud", box: hud, text: "Hello from Glassly!" }]);
  });

  // React to what the user says.
  session.transcription.on((data) => {
    session.display.render([{ type: "text", id: "hud", box: hud, text: data.text }]);
  });
});
```

You don't `new` a server or call `start()`. The host evaluates your background
bundle and hands you a `session`. Everything you do with the glasses goes through
[`session`](https://docs.glassly.ai/app-devs/core-concepts/session.md).

## The toolchain

Three npm packages, but you only ever invoke one of them directly:

| Package | Role | Where it lives |
|---|---|---|
| [`@glassly/create-miniapp`](https://www.npmjs.com/package/@glassly/create-miniapp) | Scaffolds a new project. Run once via `bunx`, never installed. | N/A |
| [`@glassly/miniapp`](https://www.npmjs.com/package/@glassly/miniapp) | The runtime SDK you `import` (`session.*`, React hooks). | your `dependencies` |
| [`@glassly/cli`](https://www.npmjs.com/package/@glassly/cli) | The `glassly` command (`dev` / `sim` / `release` / `pack` / `publish`). | your `devDependencies` |
| [`@glassly/miniapp-cli`](https://www.npmjs.com/package/@glassly/miniapp-cli) | The build tooling `glassly` drives: dev server, packer, manifest validation, JSON Schema. | your `devDependencies` |

`@glassly/create-miniapp` writes a `package.json` that already lists the other
three, so a single `bun install` brings everything down.

## What you could build

- **Live captions** that show spoken words on the HUD
- **Real-time translation** for conversations
- **Hands-free note-taking** triggered by a button or your voice
- **Navigation** prompts on supported glasses
- **Teleprompters**, fitness coaches, inspection checklists, and more

## Next steps

- [Quickstart](https://docs.glassly.ai/app-devs/getting-started/quickstart.md)
Scaffold, run, and load a miniapp on your phone in minutes.
- [Simulator](https://docs.glassly.ai/app-devs/getting-started/simulator.md)
Run a miniapp on your computer, with no phone or glasses.
- [Two-layer architecture](https://docs.glassly.ai/app-devs/core-concepts/two-layer-architecture.md)
How the background and UI layers work and talk to each other.
- [The session](https://docs.glassly.ai/app-devs/core-concepts/session.md)
The object that connects you to the glasses.
- [Mobile Bluetooth apps](https://docs.glassly.ai/bluetooth-sdk/overview.md)
Connecting to glasses directly over BLE instead.
- [AI IDE integration](https://docs.glassly.ai/app-devs/getting-started/ai-ide-integration.md)
Let a coding agent build, run, and check your miniapp.
