Quickstart Guide

Get from account setup to your first deployment in minutes with Stormkit’s automated CI/CD platform.

Quickstart Guide

This guide will walk you through creating your first deployment on Stormkit, from account setup to seeing your application live. You’ll learn how to connect your repository, configure your environment, and deploy automatically with git push.

This guide covers the Cloud Edition at app.stormkit.io. For self-hosting instructions, see our Self-Hosting Guide.

Prerequisites

Before you begin, make sure you have:

• A repository on GitHub, GitLab, or Bitbucket
• A web application (React, Vue, Next.js, Gatsby, etc.)
• Your build command and output folder (e.g., npm run build → dist/)

Step 1: Create Your Account

1. Sign in to Stormkit

   Navigate to app.stormkit.io and authenticate using your:

   • GitHub account
   • GitLab account
   • Bitbucket account

   Stormkit integrates directly with your git provider—no additional credentials needed.

2. Choose Your Team

   After signing in, you’ll see your Personal team workspace. This is your default team for managing personal projects.

   Want to collaborate? You can create additional teams later by clicking the Team Toggle in the upper left and selecting Create Team.

Step 2: Connect Your Repository

1. Create New Application

   From your team dashboard:

   1. Click New App or Create Application
   2. Select your git provider if prompted
   3. Grant Stormkit access to your repositories
2. Select Repository

   Browse or search for your repository and click Select. Stormkit will automatically detect your project type and suggest configuration defaults.

3. Name Your Application

   Give your application a memorable name. This is purely for organization in the Stormkit UI—it won’t affect your deployment URLs.

Step 3: Configure Your Environment

Every application starts with a production environment. Let’s configure it for your first deployment.

1. Navigate to Configuration

   After creating your app, you’ll be taken to your production environment. Click on Config in the left navigation menu.

2. Configure Build Settings

   Under Build settings, specify:

   Setting	Description	Examples
   Build command	Command to build your app	npm run build, yarn build, pnpm build
   Output folder	Directory containing built files	dist, build, out, .stormkit/public
   Build root	Working directory (optional)	Leave empty for repository root

   If your project doesn’t have a build command (like a static HTML site), you can leave it empty and just specify the output folder.

3. Set Environment Variables (Optional)

   Scroll to Environment Variables and add any build-time variables your application needs:

   NODE_ENV=production
   API_URL=https://api.example.com
   PUBLIC_KEY=your-public-key
   

   Variables matching /secret|_key|password/i will be automatically obfuscated in the UI for security.

4. Configure Branch Settings

   Under Settings, set:

   • Branch: Select your default production branch (usually main or master)
   • Auto publish: Toggle ON to automatically publish successful deployments
   • Auto deploy: Choose when to trigger deployments:
     • Disabled - Manual deployments only
     • All branches - Deploy every branch
     • Custom branches - Use regex patterns (e.g., main|develop)
     • Custom commits - Deploy commits matching patterns (e.g., release/*)

Step 4: Deploy Your Application

You have three ways to trigger a deployment:

Git Push (Recommended)

The easiest way to deploy is to simply push to your repository:

1. Make sure Auto Deploy is enabled in your environment config
2. Push a commit to your configured branch:

git add .
git commit -m "Initial deployment"
git push origin main

3. Stormkit receives the webhook and automatically starts building
4. Check your pull request page for a preview link with deployment status

With Auto publish enabled, successful builds on your default branch go live immediately. Commits to other branches create preview deployments.

Manual Deploy

Deploy directly from the Stormkit dashboard:

1. Click Deploy Now in the top right corner
2. Select your environment from the modal
3. Optionally override configuration for this deployment
4. Click Deploy

The deployment will start immediately and you can watch the build logs in real-time.

Deploy Trigger URL

Generate a webhook URL for external triggers:

1. Go to Config > Trigger Deploy section
2. Click Generate to create a trigger URL
3. Use it with GET or POST requests:

curl -XPOST https://api.stormkit.io/hooks/app/:app-id/deploy/:token/:environment-id \
  -H 'Content-Type: application/json' \
  -d '{"publish": true, "branch": "main"}'

Keep this URL secret—anyone with the URL can trigger deployments.

Step 5: Monitor Your Deployment

1. Watch Build Logs

   Click on your deployment to view:

   • Real-time build logs - See each build step as it executes
   • Build status - Track progress from queued → building → success/failed
   • Deployment info - Commit hash, branch, author, and timestamp
2. View Your Live Site

   Once the build succeeds:

   1. Click the Preview button to see your deployed application
   2. Your app is available at a Stormkit-provided URL like:
      https://your-app-name.stormkit.dev
      

   If Auto publish is enabled and this was a commit to your default branch, the deployment is automatically live at your production URL.

3. Troubleshoot if Needed

   If your deployment fails:

   • Check the build logs for error messages
   • Verify your build command and output folder are correct
   • Ensure all required environment variables are set
   • See our Troubleshooting Guide for common issues

Step 6: Add a Custom Domain (Optional)

1. Configure Domain

   Navigate to Config > Other > Custom Domains:

   1. Click Add Domain
   2. Enter your domain (e.g., example.com or www.example.com)
   3. Click Save
2. Update DNS Records

   Point your domain to Stormkit by adding a DNS record:

   • CNAME for subdomains: www.example.com → your-app.stormkit.dev
   • A Record for apex domains: Contact support for IP addresses

   DNS propagation typically takes 5-60 minutes.

3. Enable Analytics

   With a custom domain configured, you can enable Web Analytics:

   1. Go to your environment’s Analytics tab
   2. View visitor stats, top referrers, and popular paths
   3. All tracking is server-side with zero client cookies

   See Analytics Documentation for details.

Understanding Deployments

Stormkit deploys three types of content:

Static Files

Files in your output folder (e.g., dist/, build/) are uploaded to S3 and served through CloudFront CDN:

• HTML, CSS, JavaScript, images, fonts
• Cached globally for fast access
• Automatic gzip/brotli compression

Server Functions

For server-side rendering (SSR) with Next.js, Remix, etc.:

• Deployed to AWS Lambda
• Entry point: .stormkit/server/index.js (or server.js, main.js)
• Must export a handler function wrapped with @stormkit/serverless

import serverless from '@stormkit/serverless'

export const handler = serverless(async (req, res) => {
  res.write('Hello from ' + req.url)
  res.end()
})

API Functions

Serverless API routes with filesystem-based routing:

• Create /api folder in your repository
• Each file = separate endpoint (e.g., api/users/create.ts → /api/users/create)
• Automatic deployment to Lambda when detected
• 15-second timeout per function

See Writing API for complete guide.

Next Steps

Create More Environments

Set up staging, development, or feature environments with different configurations and branches.

Set Up Serverless APIs

Add backend functionality with Node.js/TypeScript serverless functions and filesystem routing.

Configure Auto Deployments

Fine-tune when deployments trigger using branch patterns and commit filters.

Invite Team Members

Collaborate with your team using role-based permissions (Owner, Admin, Developer).

Add Database Integration

Attach PostgreSQL schemas with automatic migrations for database-backed applications.

Optimize Images

Use on-the-fly image resizing and smart cropping with simple URL parameters.

Common Framework Examples

Vite (React/Vue)

# Build command
npm run build

# Output folder
dist

Need Help?

Deployment Docs

Detailed deployment configuration and troubleshooting

FAQ

Answers to frequently asked questions

Contact Support

Get help from the Stormkit team

---

Congratulations! You’ve deployed your first application with Stormkit. Every push to your repository will now automatically build and deploy, with preview links on pull requests and instant publishing to production.