Development Workflow

This page covers the day-to-day rhythm of building data apps, and what happens after git push — how a branch becomes a preview, and how a merged pull request reaches production.

#Your Workspace

When you’re building with Wallabi, you’ll have three things open:

1. A terminal running your dev server — this is where you run pnpm run dev. It serves your apps locally and shows status messages. You’ll start here, but you don’t need to watch it closely once it’s running.
2. A terminal running Claude Code — this is where you describe what you want to build. You’ll spend most of your time here, having a conversation with Claude Code about your app.
3. Your browser — this is where you see your apps. As Claude Code makes changes, your browser reloads automatically so you can review what’s been built and ask for adjustments.

The typical loop is: tell Claude Code what you want, watch it appear in the browser, then tell Claude Code what to change.

#Starting Your Dev Server

Each time you sit down to work:

pnpm install
pnpm run build
pnpm run dev

This starts your local dev server. Open your apps from the Wallabi app or use the URLs shown in the terminal. The dev server watches for changes and reloads automatically, so you can see updates as they happen.

#Environments

Wallabi gives you three environments, each serving a different purpose:

Environment	Where it runs	How your code gets there	Who sees it
Dev	Your computer (or codespace), via pnpm run dev	Every time you save a file	Just you
Preview	A URL Wallabi hosts for you	You create the deployment, then click Deploy	You and your reviewers
Production	Your app host’s stable URL	You click Deploy on a merged version	Your end users

Each environment has its own data scope, so your dev experiments won’t affect what your users see.

The middle column is the part that surprises people: nothing outside your own machine deploys on its own. Opening a pull request does not create a preview, and merging one does not update production. Both are things a person does deliberately, and both are covered in Shipping to Production below.

#The Begin / Ship Workflow

Wallabi provides a structured workflow for making changes. Instead of jumping straight into code, you start a session that captures what you’re trying to accomplish — and when you’re done, you wrap it up with a clean record of what was built and why.

#1. Start a session with /begin

With your dev server running, open Claude Code and type:

/begin Add a revenue breakdown chart to the sales dashboard

This tells Claude Code what you want to accomplish. It will:

• Create a session folder to track this piece of work
• Draft a summary of what you’re trying to build (requirements)
• Set up a scratchpad to capture important decisions along the way

You can give as much or as little detail as you want — a one-liner is fine. Claude Code will ask a quick follow-up if it needs more context, then get to work.

#2. Build and iterate

Once the session is started, work with Claude Code like normal:

• Describe what you want to build or change
• Let Claude Code explore your data first — it’ll look at your tables and columns before building
• Review the changes in your browser as they happen
• Ask for adjustments — “Make that a line chart instead” or “Add a drill-down table”

Behind the scenes, Claude Code keeps a running log of important decisions, pivots, and trade-offs made during the session. You don’t need to do anything — this happens automatically.

#3. Finish with /ship

When you’re happy with your changes, type:

/ship

Claude Code will:

• Finalize the requirements document with what was actually built (which may differ from the original intent — that’s normal)
• Create a technical design document capturing the key decisions and approach
• Show you both documents for review
• Commit everything

The result is a clean record of what was built and why, saved in your project under .wallabi/changes/. This is valuable context for your team — and for Claude Code itself in future sessions.

#Why this matters

Without /begin and /ship, it’s easy to lose track of why something was built a certain way. These session records mean:

• Future you can look back and understand past decisions
• Your team can review changes with full context
• Claude Code automatically picks up where you left off — when you start a new session, it sees what’s been done before and can build on it

#Working with Claude Code

Claude Code is your AI assistant for building data apps. With your dev server running, it has access to your data and the full Wallabi toolkit.

#Useful Commands

Command	What it does
/begin	Start a development session — captures what you’re building
/ship	Finish a session — finalizes documentation and commits
/create-app	Create a new data app from scratch
/generate-transform	Create or modify how your data is shaped

#Tips for Good Results

• Start with /begin — it helps Claude Code stay focused on your goal and creates a useful record of the work
• Start simple — ask for a basic table view first, then add charts and interactivity
• Explore before building — “What data sources do I have?” and “Describe the tables in [source]” help Claude Code give you better results
• Be specific — “Show monthly revenue by region with a date filter” works better than “Make a dashboard”
• Iterate — it’s easy to refine. “Make that a line chart instead” or “Add a drill-down table”

#Working with Git

Under the hood, your work is tracked with Git. The /ship command handles committing your session artifacts, but you’ll still use Git to share your work with your team.

If you’re new to Git, here’s the short version:

# Create a branch for your work
git checkout -b my-feature-name

# After making changes and running /ship, push to share
git push

Pushing puts your branch on GitHub. Open a pull request there so your team can review the changes — including the session documents that /ship generated.

Your team may have specific conventions for branch names — check with your team lead.

#What the Pull Request Check Proves

Your app host runs one check on every pull request, named Build. It installs dependencies and runs pnpm run build. That is all it does.

A green check means your app compiles. It does not mean your app works — no tests run, no page is loaded, no query is executed. A chart that throws on render, a filter wired to the wrong column, a transform returning nothing: all of these pass Build.

Nothing in Wallabi reads that check before deploying, either. If you deploy a commit that doesn’t build, the deployment fails and production keeps serving what it served before. Treat Build as a compile guard, review the pull request, and look at a preview for anything you actually need to see working.

#Versions, Deployments, and Environments

Three words do most of the work in the rest of this page, and they mean different things.

• Version — the merge commit of a pull request on your default branch. Wallabi records one every time a pull request merges into main, and identifies it by its commit SHA, with the pull request title and author alongside. Recording a version deploys nothing. It only makes that commit available to deploy.
• Deployment — a place your app host runs. It has a URL, its own API keys, its own registered apps, and its own data scope. Your production deployment is one; every preview you create is another.
• Environment — the label on a deployment that says what it’s for: production, preview, or dev.

The sentence to hold on to: a version is created by merging; a deployment happens because a person clicked Deploy. Nothing joins the two automatically.

#Shipping to Production

Deploys live in the Wallabi app: open your app host and go to the Production tab. You’ll find a Versions table listing each merged pull request — title, author, and a status:

Status	What it means
Current	The version production is serving right now
Available	Merged after whatever is live, and deployable. This is the one you click Deploy on
Deploying…	A build is running for this version
Previous	Merged before the version that’s live — behind production, not ahead of it
Rolled back	Was released, then a rollback moved past it

The Current row carries when production was last deployed and who deployed it. Below the table sit the production URL and a link to the repo.

#Deploying a Version

1. Merge your pull request into main. A new row appears in the Versions table, marked Available. Nothing has deployed.
2. If your change includes custom-table schema edits, promote the schema first — see Promoting Custom-Table Changes. Do this before step 3, not after.
3. Click Deploy on the version and confirm.
4. Wait for the build. Wallabi builds that exact commit, and only when the build succeeds does it point the production URL at the new build. The URL itself never changes, so links, bookmarks, and embeds keep working. A banner shows while a deploy is in progress; one deploy runs at a time per app host.
5. Check the result. The row you deployed becomes Current and the old one becomes Previous, with your name and the time recorded against the deploy.

A deploy takes a few minutes.

You don’t have to deploy every version. Deploying the newest one brings along everything merged before it — jumping from the fourth version straight to the sixth is normal and supported. What you can’t do is deploy backwards: to return to something older, use rollback.

#Who Can Deploy

Anyone with developer or admin access to the app host can deploy to production. There is no approval step in the deploy flow — review happens in the pull request, and in who you give app-host access to.

Every deploy and rollback is recorded with who triggered it and when, so the history is there after the fact.

#Rolling Back

Rollback returns production to the version that was live before the current one — one click, one step back. Wallabi rebuilds that commit and re-points the production URL the same way a deploy does, so a rollback takes about as long as the deploy it undoes.

The version you left behind is marked Rolled back in the table. Rollback moves exactly one step — click it again and you’re back where you started — and deploys only ever move forward from what’s live. Between them you can reach the last two versions. Anything older than that is fixed forward, with a new pull request.

#When a Deploy Fails

A failed deploy shows on the version’s row in the Versions table. What matters is what doesn’t happen: a build that fails never takes over the production URL. Production keeps serving the version it was serving. There’s no half-deployed state to clean up.

Nothing retries on your behalf, and a deploy that hasn’t finished in about fifteen minutes is marked failed even if the build later succeeds somewhere. So the fix is always to act, not to wait:

• Transient failure (a flaky install, a timeout) — click Deploy again on the same version.
• Real build failure — push a fix, merge it, and deploy the new version that appears.

#Preview Deployments

A preview is a deployment you create, pointed at a branch, so people can click through a change before it merges. Like production, it deploys when you say so — nothing watches the branch.

#Creating One

In the Wallabi app, open your app host and go to the Development tab, then Create Deployment:

Field	What to enter
Name and Slug	How you’ll recognize it in the list; the slug is URL-safe
Environment	Preview
From Branch / From URL	From Branch with your branch name — Wallabi builds and hosts it. (From URL is the other option, for registering a deployment that already runs somewhere you host.)
Expires In	7, 14, 30, or 90 days, or Never. 30 days is the default — see Deployment Lifetime

Creating the deployment kicks off the first deploy, so the row reads Setting up… for a few minutes. When it finishes, expand the row to find and copy the preview URL.

If you start an edit session from Wallabi instead of working locally, a deployment is provisioned for you as part of that flow.

#Redeploying After New Commits

A preview deploys whatever the branch’s HEAD was at the moment you asked. Push three more commits and the preview keeps serving the old one until you deploy again.

From the deployment’s row, open the ⋮ menu:

• Check for updates — asks GitHub what the branch is pointing at now.
• Deploy from branch — deploys the current HEAD. It’s only available when the branch is actually ahead of what’s deployed.

Each preview deploy gets its own URL, and the deployment’s row always shows the latest one. Share the URL from the row rather than a bookmark — an older link keeps serving the older build. (Production is the opposite: one URL, forever.)

#Preview Data

A preview deployment has its own data scope. Custom-table schema edits and test rows made against it stay there: production data is visible while you work, but nothing you do in a preview reaches production until you promote it deliberately.

#Promoting Custom-Table Changes

A deploy ships your code. It does not ship your custom tables.

Schema changes — adding a column, renaming one, hiding one — are scoped to the dev or preview deployment you made them on, and they are promoted separately. This has one practical consequence worth reading twice:

#Promoting a Schema Change

On the Development tab, a deployment with unpromoted changes shows a pending changes badge. Expand the row to see Pending schema changes — every column you’ve added, renamed, or hidden, with the table and data source it belongs to. From there:

• Promote to… → Production applies those column changes to the production scope.
• Discard pending changes throws them away instead. This can’t be undone from the UI.

If two branches touched the same column — the same position edited differently, or two new columns claiming the same name — promotion pauses and asks you to resolve each conflict: overwrite what’s in production, skip the change and keep production as it is, rename the existing column, or leave that one column out of this promotion.

#Row Data Never Promotes

Rows you added or edited in a dev or preview scope stay there permanently. Test data is test data, and there is no promote action for it — if production needs the rows, add them to production.

Two separate actions clear a deployment’s data, and both are destructive:

• Discard pending changes — drops un-promoted schema edits on that deployment.
• Reset data to production — throws away all of that deployment’s custom-table changes, schema and rows, across every data source, and re-syncs from current production.

#Deployment Lifetime

Preview and dev deployments don’t live forever. Each one carries the expiry chosen when it was created — 30 days unless you picked otherwise — and its row shows a countdown (“Deletes in 12 days”) with a Keep button beside it. Keep clears the expiry and restarts the clock. When the date arrives, the deployment is deleted automatically.

Two things worth knowing:

• A dev deployment created with no expiry still gets one if nothing has registered against it for 30 days. You get about a week’s warning in the same countdown, and Keep cancels it.
• Production is never expired. Whatever else gets cleaned up, your production deployment stays.

#When Your Change Isn’t Live

Walk the path backwards. The answer is almost always at the first step that doesn’t match.

1. Is it deployed? Production tab → Versions table. Find your pull request’s row. If it says Available, it merged but nobody has deployed it — click Deploy.
2. Did the deploy fail? A failed attempt shows on the row, and production stays on the previous version. Click Deploy again, or push a fix if the build is genuinely broken.
3. Is there a version at all? If your pull request isn’t in the table, check that it merged into main. Only merges into the default branch create a version, so a change sitting on a side branch has nothing to deploy yet.
4. Is your change a schema change? Columns don’t travel with code. Development tab → the deployment → Pending schema changes → Promote to… → Production. See Promoting Custom-Table Changes.
5. Is your change row data? Rows created in a dev or preview scope never promote. They have to be added to production directly.
6. Are you looking at the right URL? A preview deployment has its own URL and its own branch, and only redeploys when someone clicks Deploy from branch.

#Project Structure

Your app host (the project that contains your data apps — think of it as your team’s workspace) is organized like this:

your-app-host/
├── apps/                    # App host configuration
├── data-apps/               # Your data apps (one folder per app)
│   └── my-app/
│       └── src/             # App-specific code
├── packages/                # Shared data packages (transforms and sources)
└── .wallabi/
    └── changes/             # Session records from /begin and /ship

• data-apps/ is where your individual apps live — each one has its own folder
• packages/ contains the data definitions that your apps use
• .wallabi/changes/ stores the requirements and design documents from each development session