Building on Graviton
Learn the runtime, SDKs and constraints of a Stardeck app, and what differs from a plain Next.js project, before you write code in one.
Graviton is the architecture every Stardeck app runs on. Your app is a Next.js 16 App Router project that deploys as a Cloudflare Worker, talks to the platform through installed SDKs, and is carried forward by a versioned upgrade rail.
These pages are for the person writing the code. If you are looking for how to use the product — agents, dashboards, publishing — start at the documentation home.
Start here
Constraints
What the runtime refuses, and which files the platform owns. Read this first.
Compared to plain Next.js
Same framework, different boundaries. What you do differently here.
The SDKs
The packages installed in every app, and where each one's full API lives.
The shape of an app
flowchart TB
B["Browser or installed PWA"] --> D["Stardeck dispatch worker<br/>host routing · edge auth · visibility gate"]
D --> W["Your app: one Worker<br/>Next.js 16 App Router"]
W --> S["Stardeck SDKs<br/>HMAC-signed calls"]
S --> P["Platform services<br/>Data Stores · storage · email · payments · integrations"]Two things in that diagram are easy to miss, and they shape everything else:
- Your code is not the first hop. Hostname classification, tenant lookup, signed-in user resolution and public/internal visibility are decided in the shared dispatch worker before your app runs.
- Your app owns no infrastructure. There is no database you provision, no queue you run, no bucket you name. Capabilities arrive as SDKs, and the platform holds the credentials.
Working on an app
| You want to | Go to |
|---|---|
| Get repository access | Managing GitHub repository access |
| Run the app on your machine | Run your app locally |
| Give your editor platform tools | Connect Your Agent · what the tools do |
| Understand app layout, Surfaces, Modules | Structuring your app |
| Write and run tests | Testing · Tests first |
| Know which environment you are touching | Environments |
| Configure environment variables | Environment variables |
Your local checkout is not what the dashboard shows. Pushing doesn't update the hosted sandbox: load a commit into it from Git history in the toolbar, or deploy your branch as a preview. Each tracked branch has its own sandbox. See Publishing & Deployment.
Operations that are not code
Some things a Stardeck app depends on are configured through the platform rather than committed to the repository — database schema, permission keys, role grants, which Modules are on. You reach them from the dashboard, or from your coding agent once it is connected to Stardeck. The constraints page maps each one to the place you actually do it.