Compared to plain Next.js - Stardeck Documentation

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
Edit `next.config.ts` freely	Ask Stardeck for config changes	The upgrade rail patches that file
One project per audience: site, admin, POS	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

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. 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 page as restricted, assume it works.

​At a glance

​What this buys and what it costs

​The upgrade rail

​Still Next.js

At a glance

What this buys and what it costs

The upgrade rail

Still Next.js