Environments
See where each copy of your app runs, who can open it, and which data it reads and writes
Your app runs in up to four places. Each one is an environment, and each has its own URL, environment variables and data routing.
| Environment | Purpose | Who sees it |
|---|---|---|
| Sandbox | Build and test. Runs only while you're working. | Your team |
| Preview | A real deployment with its own shareable URL | Your team and anyone you share the link with |
| Staging | A 24-hour copy on fresh production data | Your team only |
| Production | Your live app at your app URL | Your users |
- Sandbox: the private copy of your app in the cloud. Each tracked branch has its own sandbox,
shared by everyone working on that branch. To work in parallel, use separate
feature branches. An app you run on your computer with
npm run devuses the sandbox's data and settings. See Run Your App Locally. - Preview: run
npx @stardeckai/cli deploy --env previewin your clone, or open Settings → Deployments → Preview on the branch. Hostnames areapp-slug-previewfor the default branch andapp-slug-preview-branch-namefor a feature branch. See Feature Branches. - Staging: a copy of your app on a fresh copy of your production data, for 24 hours. See Staging.
- Production: run
npx @stardeckai/cli deploy, or deploy from Settings → Deployments → Production. See Publishing & Deployment.
Which data each environment uses
A new app has one database. Its sandbox, its previews and the live app all read and write that same data store, so a test order placed in the sandbox shows up in the live app, and a table you change in the sandbox changes in production at the same moment.
| Environment | A new app | After you give it its own branch |
|---|---|---|
| Sandbox and your local dev app | Production's data | The branch you chose |
| Preview | Production's data | The branch you chose |
| Staging | A fresh copy, every time | A fresh copy, every time |
| Production | The store's default branch | The store's default branch |
A preview never sends email, messages or live payments, but on a new app it still reads and writes production's data. A staging always runs on its own copy and changes only that copy, except for customers and sign-ups. See Staging.
To check what your app uses today, ask your coding agent which data-store branch each environment
runs against (getProjectDataStoreEnvironments).
Give the sandbox its own data
Do this before you test with made-up orders, bookings or customers. Ask your coding agent:
Create a
devbranch of this app's database and route the sandbox to it.
It uses createDataStoreBranch, then setDataStoreEnvironmentMapping. Both need Admin access
on the store. To do it in the dashboard:
Create a branch
Open the store from Dashboard → Data Stores, go to Settings → Branches and click New branch. The branch starts as a copy of its parent's tables and rows.
Route the sandbox to it
In your app, open Settings → Data Stores. The Branch routing panel appears under the store once it has more than one branch. Set Sandbox to the new branch. Set Preview too if previews should stay off live data.
Pull your environment again
The cloud sandbox restarts on the new branch, and previews switch on their next deploy. On your
computer, run npx @stardeckai/cli env pull again and restart npm run dev.
After the split:
- Records you create in the sandbox stay there. Add real products and content on the live app.
- Schema changes made in the sandbox reach production when you deploy. The deploy review lists them under Apply data-store schema changes.
For per-branch routing and read-only links, see Connecting & routing.
Seeding data
Tables, columns and seed rows for a connected data store are platform operations, managed in Data Stores, not app migrations.
For seed data in only some environments (demo data for a preview, an initial admin in production), ask the agent for a hidden, admin-only seed button. Use it, then ask the agent to remove it.
Environment variables can also differ per environment, for example test API keys in the sandbox. See Environment Variables.
Next
Sandbox Preview
Work in the cloud sandbox and share preview builds