Zip File Deployments

Deploy applications without Git integration using zip file uploads for static sites and server applications.

Overview

Zip file deployments allow you to deploy applications without connecting a Git repository. This is useful for:

• Static site exports from any build system
• Pre-built applications from CI/CD pipelines
• Quick prototypes without version control
• Legacy applications without Git repositories
• Manual deployments from local builds

Creating a Bare App

Bare apps are applications without Git integration that accept zip file uploads.

1. Create App

   Log in to your Stormkit dashboard and click Create new app

2. Select Bare App

   Choose Create bare app from the options

3. Name Your App

   Enter a name for your application

4. Configure Environment

   Set up your app’s environment variables, domains, and other configurations

Deployment Types

Static Deployments

Deploy static websites with HTML, CSS, JavaScript, and assets.

Configuration:

• Leave Start command empty
• Upload zip with static files

Server Deployments

Deploy applications with server-side logic.

Configuration:

• Set Start command before uploading zip
• Include server executable or entry point in zip

If you specify a start command before uploading the zip file, the deployment will be treated as a server deployment instead of a static deployment.

Preparing Your Zip File

Static Site Structure

For static sites, your zip should contain build output:

my-static-site.zip
├── index.html
├── about.html
├── css/
│   └── styles.css
├── js/
│   └── app.js
└── images/
    └── logo.png

Server Application Structure

For server applications, use the .stormkit folder structure:

my-server-app.zip
├── .stormkit/
│   ├── public/       # Static assets
│   │   ├── favicon.ico
│   │   └── assets/
│   ├── server/       # Server code
│   │   ├── index.js
│   │   └── node_modules/
│   └── api/          # API functions
│       ├── users.js
│       └── posts.js
└── package.json

See How We Deploy for folder structure details.

Creating the Zip File

Using Command Line

Unix/Linux/macOS

zip -r app-build.zip /path/to/your/build/files

Using GUI

Windows:

1. Right-click the folder containing build files
2. Select Send to > Compressed (zipped) folder

macOS:

1. Right-click the folder containing build files
2. Select Compress “folder-name”

Linux (GNOME):

1. Right-click the folder containing build files
2. Select Compress…
3. Choose ZIP format

Deploying the Zip File

1. Navigate to App

   Open your bare app in the Stormkit dashboard

2. Click Deploy

   Click the Deploy button to open the deployment modal

3. Select Zip File

   Click Choose file and select your zip file

4. Configure Deployment

   Optionally set environment-specific variables or settings

5. Deploy

   Click Deploy now to start the deployment

The deployment process will:

1. Upload your zip file
2. Extract and validate contents
3. Deploy static files to CDN
4. Configure server functions (if applicable)
5. Generate preview URL

Verifying Deployment

1. Wait for Completion

   Monitor the deployment progress in the dashboard

2. Check Deployment

   After completion, click the Preview button

3. Test Application

   Open the provided URL to verify your app is live

Example: React App Deployment

Build Your App

# Build production bundle
npm run build

# Navigate to build output
cd build

# Create zip file
zip -r ../my-react-app.zip .

Typical React Build Output

build/
├── index.html
├── favicon.ico
├── manifest.json
├── static/
│   ├── css/
│   │   └── main.abc123.css
│   ├── js/
│   │   ├── main.def456.js
│   │   └── runtime.ghi789.js
│   └── media/
│       └── logo.svg
└── robots.txt

Deploy

1. Upload my-react-app.zip through Stormkit dashboard
2. Wait for deployment to complete
3. Access your app at the preview URL

Example: Next.js Static Export

Configure Static Export

next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  images: {
    unoptimized: true,
  },
}

module.exports = nextConfig

Build and Package

# Build static export
npm run build

# Create zip from out directory
cd out
zip -r ../nextjs-app.zip .

Deploy

Upload nextjs-app.zip to your bare app.

Example: Vue.js Deployment

Build Your App

# Build production bundle
npm run build

# Create zip from dist directory
cd dist
zip -r ../vue-app.zip .

Deploy

Upload vue-app.zip to your bare app.

Example: Server Application (Node.js)

Prepare Server App

my-app/
├── .stormkit/
│   └── server/
│       ├── index.js
│       ├── package.json
│       └── node_modules/
└── package.json

Server Entry Point

.stormkit/server/index.js

import serverless from '@stormkit/serverless'

export const handler = serverless(async (req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/html' })
  res.write('<h1>Hello from server</h1>')
  res.end()
})

Package and Deploy

# Install dependencies
cd .stormkit/server
npm install

# Create zip from project root
cd ../..
zip -r server-app.zip .

Upload server-app.zip to your bare app.

CI/CD Integration

Integrate zip deployments into your CI/CD pipeline.

GitHub Actions Example

.github/workflows/deploy.yml

name: Deploy to Stormkit

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build application
        run: npm run build
      
      - name: Create deployment zip
        run: |
          cd build
          zip -r ../deployment.zip .
      
      - name: Upload to Stormkit
        run: |
          curl -X POST \
            -H "Authorization: Bearer ${{ secrets.STORMKIT_API_KEY }}" \
            -F "file=@deployment.zip" \
            https://api.stormkit.io/v1/apps/${{ secrets.STORMKIT_APP_ID }}/deploy

GitLab CI Example

.gitlab-ci.yml

stages:
  - build
  - deploy

build:
  stage: build
  image: node:20
  script:
    - npm ci
    - npm run build
    - cd build && zip -r ../deployment.zip .
  artifacts:
    paths:
      - deployment.zip

deploy:
  stage: deploy
  script:
    - |
      curl -X POST \
        -H "Authorization: Bearer $STORMKIT_API_KEY" \
        -F "file=@deployment.zip" \
        https://api.stormkit.io/v1/apps/$STORMKIT_APP_ID/deploy
  only:
    - main

Limitations

No Git Integration

• No automatic deployments on push
• No deployment history from Git commits
• No branch-based environments

Manual Process

• Each deployment requires manual zip upload (unless automated via CI/CD)
• No pull request previews
• No Git-based status checks

File Size Limits

Zip file uploads have size limitations. For very large applications, consider:

• Connecting a Git repository instead
• Optimizing build output
• Removing unnecessary files

Best Practices

Include Only Necessary Files

Exclude development files from your zip:

# Don't include
- node_modules/ (except for server deployments)
- .git/
- src/
- tests/
- .env files
- README.md

Optimize Build Output

• Minify JavaScript and CSS
• Compress images
• Remove source maps (unless needed)
• Tree-shake unused code

Version Your Zips

Name zip files with versions for tracking:

my-app-v1.0.0.zip
my-app-v1.0.1.zip
my-app-v1.1.0.zip

Test Locally First

1. Extract your zip file
2. Serve it with a local server
3. Verify all assets load correctly
4. Then upload to Stormkit

Troubleshooting

Missing index.html

If you see “Top-level /index.html missing”:

• Ensure index.html is at the root of your zip
• Check that you’re zipping the build directory contents, not the directory itself

# Correct
cd build && zip -r ../app.zip .

# Incorrect (creates extra folder level)
zip -r app.zip build/

Broken Asset Paths

If CSS/JS files don’t load:

• Check that asset paths are relative or absolute
• Verify build tool configuration for production
• Ensure base URL is set correctly

Server Function Errors

If server functions fail:

• Verify .stormkit/server folder structure
• Check that entry file exports handler function
• Include all required node_modules in zip
• Ensure @stormkit/serverless is installed

Related Documentation

How We Deploy

Understand folder structure and deployment process

Configuration

Configure environment settings

Application Runtime

Deploy server applications

Troubleshooting

Fix common deployment issues