Deploying ShellApps

This guide covers deploying your ShellApp to production, including environment configuration, CI/CD, and monitoring.

Deployment Options

Vercel (Recommended)

Vercel is the recommended deployment platform for ShellApps built with Next.js.

# Install Vercel CLI
npm i -g vercel
 
# Deploy
vercel
 
# Deploy to production
vercel --prod

Self-Hosted

You can also deploy to any platform that supports Node.js:

# Build
npm run build
 
# Start production server
npm start

Docker example:

Dockerfile

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
 
FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public
EXPOSE 3000
CMD ["node", "server.js"]

Environment Variables

Variable	Required	Description
`NEXT_PUBLIC_SHELLAPPS_APP_ID`	Yes	Your app ID from Builder Tools
`SHELLAPPS_API_KEY`	Yes	Server-side API key
`NEXT_PUBLIC_AUTH_REDIRECT_URI`	Yes	OAuth callback URL
`SHELLAPPS_WEBHOOK_SECRET`	No	Webhook signature verification
`EXPERIENCE_ENDPOINT`	No	Custom Experience Platform endpoint

.env.production

NEXT_PUBLIC_SHELLAPPS_APP_ID=app_xxxxxxxxxxxx
SHELLAPPS_API_KEY=sk_live_xxxxxxxxxxxx
NEXT_PUBLIC_AUTH_REDIRECT_URI=https://myapp.com/auth/callback

CI/CD Setup

GitHub Actions

.github/workflows/deploy.yml

name: Deploy
 
on:
  push:
    branches: [main]
 
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
 
      - run: npm ci
      - run: npm run lint
      - run: npm run test
      - run: npm run build
 
      - uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
          vercel-args: --prod

Preview Deployments

Every pull request automatically gets a preview deployment on Vercel. The Experience Platform tracks preview deployments separately from production.

Domain Configuration

Custom Domain on Vercel

Add your domain in the Vercel dashboard
Update DNS records:
- A record → 76.76.21.21
- CNAME for www → cname.vercel-dns.com
Update your app's domain in the Experience Platform dashboard (opens in a new tab)

Subdomain Setup

For apps under *.shellapps.com:

Request a subdomain via Builder Tools
Vercel will automatically configure the domain
SSL is provisioned automatically

SSL/TLS

Vercel: SSL certificates are provisioned and renewed automatically
Self-hosted: Use Let's Encrypt with certbot or a reverse proxy like Caddy

# Caddy example - automatic HTTPS
caddy reverse-proxy --from myapp.example.com --to localhost:3000

Monitoring with Experience Platform

Once deployed, the Experience Platform automatically collects:

Performance metrics — Core Web Vitals, TTFB, page load times
Error tracking — Client and server errors with stack traces
User analytics — Page views, interactions (via data-t attributes)
Feedback — User-submitted feedback via the FeedbackButton

Custom Monitoring

import { experience } from '@shellapps/react-ui'
 
// Track custom events
experience.track('checkout_completed', {
  orderId: '12345',
  total: 99.99,
})
 
// Track performance marks
experience.measure('api_response_time', {
  startMark: 'api_request_start',
  endMark: 'api_request_end',
})

View all metrics in the Experience Platform dashboard (opens in a new tab).

Next Steps

Best Practices — Coding standards and patterns
Quick Start — Build your first ShellApp
Experience Platform — Deep dive into monitoring

Authentication Best Practices