App Builder

View as Markdown

App Builder

The App Builder is the workspace in the RocketRide VS Code extension that takes an app from an empty folder to a version your team can open. It owns the work that sits between an app that runs on your machine and one your team can use: scaffolding the project, previewing it against a real engine while you edit, packaging it, and deploying versions you can publish, all without leaving the editor. If you are not yet sure what an app is or whether you need one, read Apps first. Switch the RocketRide sidebar to apps mode and pick an app, or open its <name>.rrapp file, and the builder opens on it.

Where a step has a command-line equivalent, it is shown after the step, so the same loop runs from a terminal or CI.

Before you start

• The extension, installed and signed in (installation).
• Node and pnpm. Use pnpm, not npm: running npm install inside an app folder can corrupt the workspace layout. Dependencies install once at the workspace root.
• A developer id for your organization. Every app id is <developerId>.<name>. Your organization claims its developer id once, on the Deploy tab (lowercase letters and underscores, starting with a letter), and can then deploy only apps inside that namespace. Until the prefix of your app's id matches, the Deploy tab is read-only with a banner; the fix is to rename the id in package.json. Design and Package always work.

The loop

The builder's tabs, in the order you meet them the first time. After that, you come back to Design and Deploy most often.

Create (Dashboard tab)

Start from the Dashboard tab, or run RocketRide: New App from the command palette. The wizard asks for a name and a template (Blank or Dashboard) and scaffolds the app under apps/<slug>. Always create apps this way; a hand-made folder fails later with symptoms far from the cause. The scaffold starts the id at local.<slug> until your organization has a developer id; renaming the id later makes it a different app.

The <name>.rrapp file it creates is empty on purpose. Opening it opens the App Builder; the app's identity lives in package.json.

What you will edit:

File	What it is
package.json	the app manifest (appManifest): id, name, icon, README, included folders
README.md	your listing text
icon.svg	your listing icon
src/App.tsx	the screens
src/AppDescriptor.ts	how the app presents itself to the shell

rocketride app create reports --template Dashboard

Design

The Preview pane is the real shell, running against your connected engine, with your app loaded inside it. Every save rebuilds and reloads. The bundle you are previewing is a personal overlay that only you can see, and it disappears when the panel closes or the connection drops, so development work never reaches other users. Components is a live gallery of everything importable from shell, and Console shows your app's own console output as it runs.

If the preview keeps showing a sign-in screen

With Inherit Auth off, an app that requires sign-in boots signed out on purpose; turn it on to reuse your session. If it still bounces, the host session is stale: sign out of VS Code and back in, then reload the preview.

Package

The Package tab edits the appManifest block in package.json. The file is the truth, so editing it by hand is fine. Verification needs no server:

rocketride app verify ./apps/reports

Your listing

Your listing is README.md and icon.svg, declared in appManifest (readme and icon) and editable on the Package tab or by hand. Both files must live inside the app folder. Versions are immutable, so replace the scaffold README before your first deploy.

Deploy

Two verbs, and they are not the same:

• Deploy uploads your app's source; the server builds it into the next immutable version. Deploying activates nothing.
• Publish points an audience at a version: @me for your own desktop, @team/<name> for a team. First release, update, and rollback are all the same move: repoint, never rebuild. There is no org-wide rung; an org-wide audience is a team your admin maintains.

A deploy packs the app folder plus any folders listed under appManifest.include, and nothing else. Every include entry must exist.

rocketride app deploy ./apps/reports --comment "first version"

rocketride app deploy needs a deployment target (ROCKETRIDE_DEPLOY_URI and ROCKETRIDE_DEPLOY_APIKEY) and refuses to run without one; app create uses the development connection (ROCKETRIDE_URI) to vendor platform packages, and app verify needs no connection. Publishing happens on the Deploy tab.

Adding a pipeline to your app

There are two ways, and they are different features. See Apps and pipelines for the idea; this is the how-to.

Inside the app: runs per user, on demand

Put the .pipe file in the app folder and import it. The scaffold's build treats .pipe as JSON. Start it from the shell connection:

import summarizer from './summarizer.pipe';
import { useShellConnection } from 'shell';

const { client } = useShellConnection();
const { token } = await client.use({ pipeline: summarizer, useExisting: true });

Every signed-in user gets their own instance. Start it once per session and keep the token; useExisting: true re-attaches after a reload instead of failing because the pipeline is already running. The pipeline ships with the app on deploy. Use this for work that happens when the user asks for it.

Outside the app: shared, on a schedule

Build the pipeline as its own project and deploy it separately:

rocketride deploy add pipelines/nightly-report.pipe --comment "v1"
rocketride deploy publish <projectId> 1 --team <teamId>

The app does not start this pipeline. It imports the .pipe for its identity only and asks the shell client for the running task's token (getTaskToken) to attach to the instance the team is running:

import nightly from '../../../pipelines/nightly-report.pipe'; // identity only
const projectId = String(nightly.project_id);

Outside its schedule window there is no running instance and no token. That is the normal state, not an error; show the feature as offline and check again later. Deploying the app does not carry this pipeline, so deploy it on its own whenever it changes.

	Inside the app	Outside the app
Where the .pipe lives	in the app folder	its own project
Who runs it	one instance per signed-in user	one instance for the team
When it runs	when the app asks	on its schedule
How it deploys	with the app	separately, rocketride deploy

Next steps

• Shell API: hooks, the descriptor, and the manifest, when you code by hand.
• CLI: the full command reference.
• Building with a coding agent? The bundle the extension installs already contains the complete app reference; point your agent at ROCKETRIDE_APPS.md.