Zip File Deployments

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.

​

Overview

• 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

​

Deployment Types

​

Static Deployments

• Leave Start command empty
• Upload zip with static files

​

Server Deployments

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

​

Preparing Your Zip File

​

Static Site Structure

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

​

Server Application 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

​

Creating the Zip File

​

Using Command Line

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

​

Using GUI

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

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

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

​

Deploying the Zip File

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

​

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

/** @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

​

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

​

Example: Server Application (Node.js)

​

Prepare Server App

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

​

Server Entry Point

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 .

​

CI/CD Integration

​

GitHub Actions Example

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

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

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

​

Best Practices

​

Include Only Necessary Files

# 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

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

• 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

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

​

Server Function Errors

• 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