> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stardeck.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Compared to plain Next.js

> A Stardeck app is a stock Next.js App Router project. What differs is where the boundaries are — the runtime, the data layer, auth, deploys, and who owns the upgrade.

A Stardeck app is **stock Next.js** — App Router, React Server Components,
`page.tsx`, `route.ts`, `layout.tsx`, Tailwind. Nothing proprietary replaces the
framework, and your React is portable.

What differs is everything around it: where requests are decided, where data
lives, who holds credentials, and who owns keeping the app current.

## At a glance

| On your own Next.js app                         | On Graviton                                          | Why                                                                                                                          |
| ----------------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Choose a host and run `deploy`                  | Push `main`, publish from the dashboard              | The app builds to a Cloudflare Worker and is uploaded into Stardeck's dispatch namespace                                     |
| Pick a runtime per route                        | Workers everywhere                                   | No Node.js runtime — which is also why `middleware.ts` must not be renamed to `proxy.ts`                                     |
| Provision Postgres, pick an ORM, own migrations | Data Store + `data-store-sdk` (Kysely)               | Schema is a platform operation; the driver is HTTP, so no interactive transactions                                           |
| Add NextAuth, Clerk, or roll your own           | `project-auth`                                       | Sign-in, RBAC, SSO and the admin/user dashboards ship with it, and visibility is enforced at the edge                        |
| Guard routes in middleware                      | Guard in the layout **and** in each API handler      | Host classification, tenant lookup and public/internal gating happen before your code; API paths are never edge-gated        |
| `vercel cron` or a cron container               | `scheduling-sdk`                                     | The platform calls your deployment on a schedule                                                                             |
| Wire Stripe, an email provider, an S3 bucket    | `payments-sdk`, `email-sdk`, storage-type Data Store | The platform holds credentials; every call is HMAC-signed by the SDK                                                         |
| Rely on ISR and the data cache                  | Treat rendering as per-request; cache deliberately   | No incremental cache is configured — see [Constraints](/graviton/constraints#rendered-output-is-not-cached-between-requests) |
| Edit `next.config.ts` freely                    | Ask Stardeck for config changes                      | The upgrade rail patches that file                                                                                           |
| One project per audience: site, admin, POS      | [Surfaces](/app-structure/surfaces) in one repo      | Each gets its own hostname, icon and install identity from one deploy                                                        |
| Own your dependency and framework upgrades      | The upgrade rail moves the app forward               | Over 130 versioned upgrade steps carry existing apps to the current platform version                                         |
| `.env.local` you maintain                       | `npm run env:pull` from the platform                 | Secrets are stored and decrypted by the platform, per environment                                                            |
| Webhooks to `localhost` via a tunnel            | Exercise inbound traffic in the sandbox              | Nothing inbound is routed to a local dev server, by design                                                                   |

## What this buys and what it costs

```mermaid theme={null}
flowchart TB
    subgraph Y["What you stop owning"]
        Y1["Infrastructure and credentials"]
        Y2["Auth, RBAC and the sign-in surface"]
        Y3["Framework and dependency upgrades"]
        Y4["Hostnames, TLS and PWA identity per audience"]
    end
    subgraph C["What you accept"]
        C1["Worker runtime limits, including a 10 MiB bundle"]
        C2["No interactive database transactions"]
        C3["Some files and operations are platform-owned"]
        C4["Deploys go through the platform, not your CI"]
    end
    Y --> V["One codebase, many audiences,<br/>that keeps moving forward"]
    C --> V
```

The trade is deliberate: less infrastructure to own, fewer places to be
inventive. Every constraint is written down, and each one is enforced by something
you can see — a lint rule, a build failure, or a file header.

## The upgrade rail

The part with no equivalent in a normal project. A repository someone hands you is
frozen the day it ships. Here, the platform ships versioned upgrade steps that run
against existing apps: they install new SDK versions, rewrite platform-owned
files, and — when a change is breaking — carry instructions that let the agent
rewrite your call sites.

```mermaid theme={null}
sequenceDiagram
    participant P as Platform release
    participant R as Upgrade rail
    participant A as Your app
    P->>R: publish SDK version, add an upgrade step
    R->>A: install the new dependency
    R->>A: rewrite platform-owned files
    R->>A: instructions for breaking changes
    A->>A: call sites updated
```

Which changes how you write code, in two ways:

* **Stay on the SDK surface.** Code that uses an SDK's documented API is carried
  forward. Code that reaches around it — hand-built platform requests, copies of
  generated files — is what breaks on upgrade.
* **`AGENTS.md` is not yours to edit.** It is regenerated every upgrade. Project
  conventions belong in a file the platform does not own.

## Still Next.js

Things that work exactly as you expect, with no Stardeck-specific wrapper: the App
Router and route groups, Server Components and Server Actions, `layout.tsx`
composition, streaming, `next/image` (against configured hosts), Tailwind,
`react-hook-form`, TanStack Query, Zod, Playwright and Vitest.

If a Next.js pattern is not listed on the [Constraints](/graviton/constraints)
page as restricted, assume it works.