Apps
Build Shopify and web apps from models, actions and Next.js pages. Inference Bureau stores the data, runs the code, hosts the pages and keeps development and production apart.
What it is
An app is a folder of files. You describe the data as models, write the code that changes it as actions, and put pages in a Next.js app under web/. Inference Bureau keeps the files, stores the records, runs the actions inside the app's own deployment, and serves the pages at the app's address on inferencebureau.app.
An app is a folder: api/models/<model>/schema.ib.ts, api/models/<model>/actions/*.ts, global actions in api/actions/, and metadata in *.ib.ts files.
Concepts
| Term | Meaning |
|---|---|
| App | One product, owned by a team. It has a name, a slug (used in URLs and the CLI) and a platform. |
| Environment | development and production. Each has its own files, records, event log, environment variables and, for Shopify, its own Shopify app. |
| File version | Every save to an environment's files bumps its version by one. The files live in Inference Bureau's database, not on your disk or a git host. |
| Model | A kind of record, defined by api/models/<model>/schema.ib.ts. See Models. |
| Action | A function that changes records: a model's create, update, delete or custom action, or a global one. See Actions. |
| Event | One line of the environment's log: a sync, a webhook, an action run, a storefront request, a build. See Logs. |
| Deploy | Copies development's files to production and builds them. Production changes no other way. See Deploys. |
| Plan | The team's Apps plan (Free, Pro or Scale): allowances pooled across every app's production, charged to the team's balance. See Plans and usage. |
Platforms
The platform is chosen when the app is created and decides how people sign in and where the app appears. Models, actions, files, environments and Logs work the same on both.
| Platform | Starts with | Notes |
|---|---|---|
| Shopify | shopifyShop with install and uninstall actions, an embedded admin page, a storefront block and two app proxy routes | Each environment gets its own Shopify app in your Partner organization. See Shopify apps. |
| Web | user and session models, a signUp action, the signed-in and unauthenticated roles, a home page, and email and password sign-up, sign-in and sign-out (web/lib/auth.ts) with members-only pages in web/app/(signed-in)/, email confirmation and password reset | No Shopify app or credentials. Emails go through your own Resend account: connect it on Settings → Integrations. |
A Shopify session's and a proxy request's api reach only their store's records, held to the roles in accessControl/permissions.ib.ts. See Access control.
Environments
| Development | Production | |
|---|---|---|
| Files | Change on every sync from ib-apps or the dashboard editor | Read-only. Change only by a deploy |
| Code | A live next dev server in a sandbox. Saves hot-reload with no build. It sleeps when idle and wakes on the next request, or as soon as ib-apps dev starts; a wake writes only the files that changed while it slept | An immutable build per deploy |
| Records | Its own. Schema changes take effect as they are saved | Its own. Schema changes take effect on a deploy |
| Shopify app | Installed on development stores | Installed on the merchant's store |
| Logs, variables, webhooks | Per environment | Per environment |
Production doesn't exist until the first deploy. Its Logs, Ops and Preview say so until then.
More development environments
An app can have up to ten development environments: development and others beside it, such as feature-x, so two people or a feature branch and a fix don't share one database and dev server. Create one from the environment switcher's Create a new development environment (admins). It starts from a copy of another environment's files, or from the starter files, and has its own records, dev server, hostname and Logs. A Shopify app gets its own Shopify app, <app>-<name>, made with development's Shopify sign-in and scopes.
Its environment variables read development's values until it has its own. Set them on Settings → Environment variables there, or copy every value from another environment with Copy values from. Sync a folder with it using ib-apps dev --env feature-x; the folder remembers it. Deploy in that environment ships its files to production. Deleting one (the switcher's ⋮ menu) removes its files and own values and frees its name; its Shopify app stays in your Partner organization until you delete it there.
Hosting
Each environment has its own hostname on inferencebureau.app:
| Environment | Address |
|---|---|
| Production | <app>.inferencebureau.app |
| Development | <app>--development.inferencebureau.app |
| Another development environment | <app>--<name>.inferencebureau.app |
<app> is the app's host name, normally its slug. A router in front of the domain sends each request to production's deployment or development's dev server. While a sleeping dev server starts, it shows a "starting" page. Visitors and merchants never see the hosting provider: its headers are stripped and its error pages replaced.
Each build moves web/ to the deployment's root (Next.js App Router), copies api/ beside it, and adds the route that runs actions. Next.js type-checks the pages during the build; a failed build leaves the version that's live in place.
In the dashboard
Apps are under Apps in the team sidebar, with the team's Usage and Plan and usage beneath (see Plans and usage). An app's pages have the app and environment switchers at the top, with the assistant's pill in the middle, Docs and, in development, Deploy. The apps list's row menu can Fork an app (copy development's or production's files into a new app) or delete it.
| Section | What it does |
|---|---|
| Files | The environment's files. A model folder shows schema as a field editor and data as a record grid beside its actions/; action files open as code with a Run action button. TypeScript files get completions (api.'s models, a filter's fields), types on hover and type errors as you type, checked against the SDK and your app's generated types. Production is read-only. |
| Preview | The app at its own address, with its web/ files beside it. Shopify admin pages get a preview session for an installed store. A web app's development can be previewed signed out or as one of its users. See Preview. |
| Logs | The environment's events with a query bar and saved views, plus Problems and the Terminal panel. See Logs. |
| Ops | Requests by status, errors, action runs and time spent in the environment. |
| Settings | General, Shopify, Installs and Deploys, then Environment variables, API keys and Webhooks. |
Environment variables
Set them on Settings → Environment variables and read them in the app's code as process.env.NAME. Every value is encrypted; marking one secret only keeps it hidden in the dashboard until revealed. Production uses development's value unless it has its own. Development's dev server restarts when one changes; production gets the change on its next deploy.
Inference Bureau sets these itself, and their names can't be used, nor can anything starting with IB_, VERCEL, __NEXT or NEXT_RUNTIME, or NODE_ENV, PORT, HOSTNAME, PATH and HOME. An app can have up to 200 variables, each up to 32 KB:
| Variable | Value |
|---|---|
IB_APP | The app's slug |
IB_APP_URL | Where visitors reach the environment, such as https://wholesale-portal.inferencebureau.app, or production's primary domain. Use it for links the app sends out |
IB_ENVIRONMENT | development or production |
IB_API_URL | Inference Bureau's API origin |
IB_ENVIRONMENT_TOKEN | The environment's token, which the SDK uses to call back. See Environment tokens |
IB_FILE_VERSION | Production only: the file version it was built from |
NEXT_PUBLIC_SHOPIFY_API_KEY | Shopify apps: the environment's client id, for App Bridge |
Secrets from 1Password
A variable's value can be a 1Password secret reference instead of the secret, so the secret stays in your vault. Connect the team once on Settings → Integrations → 1Password with a service account token: create one at 1password.com in a browser (Developer, then Service Account under Access Tokens) with read access to the vaults your apps use. Service accounts come with 1Password Teams and Business. Then set a value to the reference, copied from the field's menu in 1Password with Copy Secret Reference:
| Variable | Development | Production |
|---|---|---|
STRIPE_SECRET_KEY | op://Acme Dev/Stripe/secret key | op://Acme Prod/Stripe/secret key |
The app's code reads process.env.STRIPE_SECRET_KEY as the secret. Each environment has its own reference, so production's secrets can live in a vault development never reads.
- When it's read. Every build asks 1Password for each reference again. A dev server waking uses what the last build or sync read, since 1Password limits how often a service account reads.
- Rotating a secret. After changing it in 1Password, press Sync now in the integration's drawer: development restarts with the new value and production gets it on its next deploy.
- When one doesn't resolve. A missing item or field, a vault the service account can't read, or no service account fails the build (or the dev server's start) with the variable's name and the reason, never starts the app with the reference as its value. When 1Password can't be reached, what the reference last resolved to is used.
Next steps
- Getting started: install
ib-apps, create an app and sync it. - Models and Actions: the data and the code that changes it.
- Shopify apps: connect Shopify, sync products, and reach the admin and the storefront.
- Examples: reviews, a wishlist, a product tagger, a product quiz, a Notion sync and a bundler with a Shopify Function, file by file.
- Plans and usage: what Free, Pro and Scale include, and what happens at a limit.
- Limits: every hard limit in one place, to check before committing to a design.