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

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

<Steps>
  <Step title="Create App">
    Log in to your Stormkit dashboard and click **Create new app**
  </Step>

  <Step title="Select Bare App">
    Choose **Create bare app** from the options
  </Step>

  <Step title="Name Your App">
    Enter a name for your application
  </Step>

  <Step title="Configure Environment">
    Set up your app's environment variables, domains, and other configurations
  </Step>
</Steps>

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

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

## Preparing Your Zip File

### Static Site Structure

For static sites, your zip should contain build output:

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

```bash theme={null}
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](/deployments/how-we-deploy) for folder structure details.

## Creating the Zip File

### Using Command Line

<CodeGroup>
  ```bash Unix/Linux/macOS theme={null}
  zip -r app-build.zip /path/to/your/build/files
  ```

  ```bash Windows (PowerShell) theme={null}
  Compress-Archive -Path "C:\path\to\build" -DestinationPath "app-build.zip"
  ```

  ```bash From Build Directory theme={null}
  cd build
  zip -r ../app-build.zip .
  ```
</CodeGroup>

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

<Steps>
  <Step title="Navigate to App">
    Open your bare app in the Stormkit dashboard
  </Step>

  <Step title="Click Deploy">
    Click the **Deploy** button to open the deployment modal
  </Step>

  <Step title="Select Zip File">
    Click **Choose file** and select your zip file
  </Step>

  <Step title="Configure Deployment">
    Optionally set environment-specific variables or settings
  </Step>

  <Step title="Deploy">
    Click **Deploy now** to start the deployment
  </Step>
</Steps>

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

<Steps>
  <Step title="Wait for Completion">
    Monitor the deployment progress in the dashboard
  </Step>

  <Step title="Check Deployment">
    After completion, click the **Preview** button
  </Step>

  <Step title="Test Application">
    Open the provided URL to verify your app is live
  </Step>
</Steps>

## Example: React App Deployment

### Build Your App

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

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

```javascript next.config.js theme={null}
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  images: {
    unoptimized: true,
  },
}

module.exports = nextConfig
```

### Build and Package

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

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

```bash theme={null}
my-app/
├── .stormkit/
│   └── server/
│       ├── index.js
│       ├── package.json
│       └── node_modules/
└── package.json
```

### Server Entry Point

```javascript .stormkit/server/index.js theme={null}
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

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

```yaml .github/workflows/deploy.yml theme={null}
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

```yaml .gitlab-ci.yml theme={null}
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:

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

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

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

<CardGroup cols={2}>
  <Card title="How We Deploy" icon="diagram-project" href="/deployments/how-we-deploy">
    Understand folder structure and deployment process
  </Card>

  <Card title="Configuration" icon="gear" href="/deployments/configuration">
    Configure environment settings
  </Card>

  <Card title="Application Runtime" icon="server" href="/deployments/application-runtime">
    Deploy server applications
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/deployments/troubleshooting">
    Fix common deployment issues
  </Card>
</CardGroup>