> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/stormkit-io/stormkit-io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Note>
  This guide covers the **Cloud Edition** at [app.stormkit.io](https://app.stormkit.io). For self-hosting instructions, see our [Self-Hosting Guide](/self-hosting/getting-started).
</Note>

## 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

<Steps>
  <Step title="Sign in to Stormkit">
    Navigate to [app.stormkit.io](https://app.stormkit.io) and authenticate using your:

    * **GitHub** account
    * **GitLab** account
    * **Bitbucket** account

    Stormkit integrates directly with your git provider—no additional credentials needed.
  </Step>

  <Step title="Choose Your Team">
    After signing in, you'll see your **Personal** team workspace. This is your default team for managing personal projects.

    <Note>
      Want to collaborate? You can create additional teams later by clicking the **Team Toggle** in the upper left and selecting **Create Team**.
    </Note>
  </Step>
</Steps>

## Step 2: Connect Your Repository

<Steps>
  <Step title="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
  </Step>

  <Step title="Select Repository">
    Browse or search for your repository and click **Select**. Stormkit will automatically detect your project type and suggest configuration defaults.
  </Step>

  <Step title="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>
</Steps>

## Step 3: Configure Your Environment

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

<Steps>
  <Step title="Navigate to Configuration">
    After creating your app, you'll be taken to your production environment. Click on **Config** in the left navigation menu.
  </Step>

  <Step title="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             |

    <Warning>
      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.
    </Warning>
  </Step>

  <Step title="Set Environment Variables (Optional)">
    Scroll to **Environment Variables** and add any build-time variables your application needs:

    ```bash theme={null}
    NODE_ENV=production
    API_URL=https://api.example.com
    PUBLIC_KEY=your-public-key
    ```

    <Note>
      Variables matching `/secret|_key|password/i` will be automatically obfuscated in the UI for security.
    </Note>
  </Step>

  <Step title="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>
</Steps>

## Step 4: Deploy Your Application

You have three ways to trigger a deployment:

<Tabs>
  <Tab title="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:

    ```bash theme={null}
    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

    <Note>
      With **Auto publish** enabled, successful builds on your default branch go live immediately. Commits to other branches create preview deployments.
    </Note>
  </Tab>

  <Tab title="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.
  </Tab>

  <Tab title="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:

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

    <Warning>
      Keep this URL secret—anyone with the URL can trigger deployments.
    </Warning>
  </Tab>
</Tabs>

## Step 5: Monitor Your Deployment

<Steps>
  <Step title="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
  </Step>

  <Step title="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
       ```

    <Note>
      If **Auto publish** is enabled and this was a commit to your default branch, the deployment is automatically live at your production URL.
    </Note>
  </Step>

  <Step title="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](/deployments/troubleshooting) for common issues
  </Step>
</Steps>

## Step 6: Add a Custom Domain (Optional)

<Steps>
  <Step title="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**
  </Step>

  <Step title="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.
  </Step>

  <Step title="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](/features/analytics) for details.
  </Step>
</Steps>

## Understanding Deployments

Stormkit deploys three types of content:

<AccordionGroup>
  <Accordion title="Static Files" icon="file">
    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
  </Accordion>

  <Accordion title="Server Functions" icon="server">
    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`

    ```javascript theme={null}
    import serverless from '@stormkit/serverless'

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

  <Accordion title="API Functions" icon="function">
    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](/features/writing-api) for complete guide.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Create More Environments" icon="layer-group" href="/docs/features/multiple-environments">
    Set up staging, development, or feature environments with different configurations and branches.
  </Card>

  <Card title="Set Up Serverless APIs" icon="code" href="/docs/features/writing-api">
    Add backend functionality with Node.js/TypeScript serverless functions and filesystem routing.
  </Card>

  <Card title="Configure Auto Deployments" icon="rocket" href="/docs/deployments/auto-deployments">
    Fine-tune when deployments trigger using branch patterns and commit filters.
  </Card>

  <Card title="Invite Team Members" icon="users" href="/docs/features/teams-and-roles">
    Collaborate with your team using role-based permissions (Owner, Admin, Developer).
  </Card>

  <Card title="Add Database Integration" icon="database" href="/docs/features/database">
    Attach PostgreSQL schemas with automatic migrations for database-backed applications.
  </Card>

  <Card title="Optimize Images" icon="image" href="/docs/features/image-optimization">
    Use on-the-fly image resizing and smart cropping with simple URL parameters.
  </Card>
</CardGroup>

## Common Framework Examples

<CodeGroup>
  ```bash Vite (React/Vue) theme={null}
  # Build command
  npm run build

  # Output folder
  dist
  ```

  ```bash Next.js theme={null}
  # Build command
  npm run build

  # Output folder
  .next
  ```

  ```bash Create React App theme={null}
  # Build command
  npm run build

  # Output folder
  build
  ```

  ```bash Gatsby theme={null}
  # Build command
  gatsby build

  # Output folder
  public
  ```

  ```bash Docusaurus theme={null}
  # Build command
  npm run build

  # Output folder
  build
  ```
</CodeGroup>

## Need Help?

<CardGroup cols={3}>
  <Card title="Deployment Docs" icon="book" href="/docs/deployments/introduction">
    Detailed deployment configuration and troubleshooting
  </Card>

  <Card title="FAQ" icon="question" href="/docs/welcome/getting-started">
    Answers to frequently asked questions
  </Card>

  <Card title="Contact Support" icon="envelope" href="/docs/welcome/contact-us">
    Get help from the Stormkit team
  </Card>
</CardGroup>

***

**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.