Build your first Shell app

Create a Shell app, preview it locally, publish it and open it on your workspace's Shell site.

In this guide you create a Shell app from the starter kit, preview it on your computer, publish it and open it in your workspace's Shell site. It takes about fifteen minutes.

Before you start

The Writer, Admin or Owner role in a workspace.
Node.js 20 or later, and the gf CLI: npm install -g @groundfloorcloud/cli, then gf login and gf workspaces use <workspace-id>.

Prefer not to install anything? Create the app in the Client Portal, then use Develop online on its page to do steps 2–4 in your browser.

1. Create the app

gf apps create --name "My First App" --slug my-first-app

Go to Build → Apps, register a new app with the Shell kind, and give it the slug my-first-app.

The slug is the app's short name. It appears in the app's address and ties your code to the app.

2. Get the starter kit

gf apps init --slug my-first-app
cd my-first-app
npm install

This downloads the starter kit into my-first-app/ and sets the app's ID in the two places it lives: appId in groundfloor.manifest.json and APP_ID in src/appIdentity.ts. Both must match the slug.

You can also download the starter kit as a ZIP, or from the app's page in the Client Portal, and set those two values yourself.

3. Preview it locally

npm run dev

Open http://localhost:4175. The kit runs your app inside a stand-in for the Shell. Because you signed in with gf login, it reads your workspace's real data; to use sample data instead, run npm run dev:fixtures.

Your pages live in src/pages/, and the routes are listed in groundfloor.manifest.json. See Manifest and routes.

4. Publish it

npm run release
gf apps publish --path release.zip

npm run release builds your app into release.zip. Always publish that file rather than zipping the build folder yourself. You can also upload release.zip on the app's Releases tab in the Client Portal. A release bundle can be up to 32 MiB.

5. Open it

Go to your workspace's Shell site:

https://<workspace-slug>.app.groundfloor.cloud/apps/my-first-app

Your app appears inside the Shell, with its pages in the navigation.

Check that it worked

The app's page in the Client Portal shows the new release and its build number. If the Shell shows an error instead of your app, see Troubleshooting.

Next steps

Sign-in and users — let your users sign in, and know who they are.
Data — read and write records.
Styling — match the Shell's look.

Build your first Shell app

On this page