Build Your First ShellApp

Get a ShellApp up and running in under 10 minutes. This guide walks you through creating a Next.js app with the full ShellApps platform integration.

Step 1: Create a Next.js App

npx create-next-app@latest my-shellapp --typescript --tailwind --app
cd my-shellapp

Step 2: Install @shellapps/react-ui

npm install @shellapps/react-ui @shellapps/auth-sdk

Step 3: Set Up ThemeProvider

Wrap your app with the ShellApps ThemeProvider to get consistent styling across the platform.

app/layout.tsx

import { ThemeProvider } from '@shellapps/react-ui'
import '@shellapps/react-ui/styles.css'
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <ThemeProvider
          theme="system"
          accentColor="blue"
        >
          {children}
        </ThemeProvider>
      </body>
    </html>
  )
}

Step 4: Activate Builder Tools

Before you can register your app with the platform, you need Builder access.

Go to auth.shellapps.com/settings/builder (opens in a new tab)
Sign in with your ShellApps ID
Click Activate Builder Tools
You'll receive an API key and app credentials

# Save your credentials as environment variables
SHELLAPPS_API_KEY=your-api-key

Step 5: Create Your App in Builder

Head to builder.shellapps.com (opens in a new tab) to create your app configuration:

Sign in with your ShellApps ID
Click Create New App
Fill in your app details — name, description, and domain
Once created, you'll get an App ID — copy this for the next steps

# Add your App ID to environment variables
NEXT_PUBLIC_SHELLAPPS_APP_ID=your-app-id

Your app config in Builder is the central record for your ShellApp. It connects your app to the Experience Platform, manages access, and controls how it appears in the App Marketplace (opens in a new tab).

Step 6: Register App with Experience Platform

curl -X POST https://experience.shellapps.com/api/apps \
  -H "Authorization: Bearer $SHELLAPPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-shellapp",
    "domain": "my-shellapp.vercel.app",
    "description": "My first ShellApp"
  }'

Step 7: Add ExperienceProvider, ErrorBoundary & FeedbackButton

These components connect your app to the Experience Platform for analytics, error tracking, and user feedback.

app/providers.tsx

'use client'
 
import {
  ExperienceProvider,
  ErrorBoundary,
  FeedbackButton
} from '@shellapps/react-ui'
 
export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ExperienceProvider appId={process.env.NEXT_PUBLIC_SHELLAPPS_APP_ID!}>
      <ErrorBoundary
        fallback={({ error, reset }) => (
          <div>
            <h2>Something went wrong</h2>
            <p>{error.message}</p>
            <button onClick={reset}>Try again</button>
          </div>
        )}
      >
        {children}
        <FeedbackButton position="bottom-right" />
      </ErrorBoundary>
    </ExperienceProvider>
  )
}

Update your layout to include the providers:

app/layout.tsx

import { ThemeProvider } from '@shellapps/react-ui'
import { Providers } from './providers'
import '@shellapps/react-ui/styles.css'
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <ThemeProvider theme="system" accentColor="blue">
          <Providers>{children}</Providers>
        </ThemeProvider>
      </body>
    </html>
  )
}

Step 8: Add Tracking with `data-t` Attributes

The Experience Platform automatically tracks user interactions on elements with data-t attributes. No extra JavaScript required.

app/page.tsx

export default function Home() {
  return (
    <main>
      <h1>Welcome to My ShellApp</h1>
 
      <button data-t="cta-signup">
        Get Started
      </button>
 
      <nav data-t="main-nav">
        <a href="/features" data-t="nav-features">Features</a>
        <a href="/pricing" data-t="nav-pricing">Pricing</a>
        <a href="/docs" data-t="nav-docs">Docs</a>
      </nav>
 
      <section data-t="hero-section">
        <p>Build something amazing.</p>
      </section>
    </main>
  )
}

Events are automatically sent to the Experience Platform where you can view them in your dashboard.

Step 9: Deploy

Deploy to Vercel (recommended) or any platform that supports Next.js:

# Deploy to Vercel
npx vercel
 
# Set environment variables
npx vercel env add NEXT_PUBLIC_SHELLAPPS_APP_ID
npx vercel env add SHELLAPPS_API_KEY

After deploying, update your app's domain in the Experience Platform dashboard.

What's Next?

Authentication — Add login and signup with ShellApps ID
Deployment — Advanced deployment and CI/CD configuration
Best Practices — Coding standards and patterns
Experience Platform — Deep dive into analytics and feedback

Home Authentication