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

# How Stormkit Deploys

> Understanding the deployment process, folder structure, and artifact handling in Stormkit.

## Deployment Overview

Stormkit leverages AWS infrastructure for deployment. Each deployment can contain three types of files:

* **Static files** - CDN-served assets (HTML, CSS, JS, images)
* **Server files** - Server-side rendering functions
* **API files** - Serverless API endpoints

All files are securely stored in S3 buckets and deployed to AWS Lambda (for functions) or served via CloudFront CDN (for static assets).

## Folder Structure

Stormkit looks for a specific folder structure to determine what to deploy.

### Default Structure

By default, Stormkit looks for a `.stormkit` subfolder:

```bash theme={null}
.stormkit/
├── public/         # Static assets
├── server/         # SSR functions
└── api/            # API endpoints
```

### Custom Output Folder

You can specify a different output folder in **Environment** > **Config** > **Output folder**.

If you specify a custom folder, Stormkit validates the same structure:

```bash theme={null}
custom-output/
├── public/         # Static assets
├── server/         # SSR functions
└── api/            # API endpoints
```

### Fallback Folders

If no `.stormkit` folder exists and no output folder is specified, Stormkit checks these common folders in order:

1. `out`
2. `output`
3. `dist`
4. `build`
5. `public`

If none are found, Stormkit uploads everything under the build root.

## Static Files

All files under `.stormkit/public` (or the configured output folder) are deployed to S3 and served by CloudFront CDN.

### Example Static Structure

```bash theme={null}
.stormkit/public/
├── index.html
├── about.html
├── assets/
│   ├── app.css
│   └── app.js
└── images/
    └── logo.png
```

These files are served directly from the CDN:

* `https://your-app.com/index.html`
* `https://your-app.com/assets/app.css`
* `https://your-app.com/images/logo.png`

### Content Types

Stormkit automatically sets appropriate `Content-Type` headers based on file extensions:

* `.html` → `text/html`
* `.css` → `text/css`
* `.js`, `.mjs` → `application/javascript`
* `.json` → `application/json`
* `.png` → `image/png`
* `.jpg`, `.jpeg` → `image/jpeg`

## Server Files

Server files enable server-side rendering (SSR) and are deployed as AWS Lambda functions.

### Entry Point Detection

In the `server` subfolder, Stormkit looks for an entry file in this order:

1. `index.js`
2. `index.mjs`
3. `index.cjs`
4. `server.js`
5. `server.mjs`
6. `server.cjs`

If no entry file is found, the function returns a 404 error.

### Handler Export

The entry file must export a function named `handler` wrapped by the `@stormkit/serverless` helper:

```typescript .stormkit/server/index.js theme={null}
import serverless from '@stormkit/serverless'
import http from 'http'

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

### Request/Response Objects

The handler receives standard Node.js `http.IncomingMessage` and `http.ServerResponse` objects:

```typescript theme={null}
interface IncomingMessage {
  url: string
  method: string
  headers: Record<string, string>
  // ... standard Node.js request properties
}

interface ServerResponse {
  writeHead(statusCode: number, headers?: Record<string, string>): void
  write(chunk: string | Buffer): void
  end(): void
  // ... standard Node.js response methods
}
```

### Dependencies

Stormkit automatically bundles Node.js dependencies found in your server code. Dependencies are detected by scanning for `import` and `require` statements.

To include additional dependencies:

```json package.json theme={null}
{
  "bundleDependencies": ["express", "dotenv"]
}
```

## API Files

API files follow file-system routing, similar to Next.js API routes or Vercel functions.

### File System Routing

Each file in the `api` folder becomes an endpoint:

```bash theme={null}
.stormkit/api/
├── hello.js          # /api/hello
├── users.js          # /api/users
└── posts/
    ├── index.js      # /api/posts
    └── [id].js       # /api/posts/:id
```

### Handler Export

Each API file exports a default function:

```typescript .stormkit/api/hello.js theme={null}
import type { IncomingMessage, ServerResponse } from 'http'

export default async (req: IncomingMessage, res: ServerResponse) => {
  res.writeHead(200, { 'Content-Type': 'application/json' })
  res.write(JSON.stringify({ message: 'Hello from API' }))
  res.end()
}
```

<Note>
  API functions don't need the `serverless` wrapper. Stormkit handles the wrapper automatically for API routes.
</Note>

### Dynamic Routes

Use bracket notation for dynamic parameters:

```typescript .stormkit/api/users/[id].js theme={null}
export default async (req, res) => {
  const { id } = req.params // Extract from URL
  
  res.writeHead(200, { 'Content-Type': 'application/json' })
  res.write(JSON.stringify({ userId: id }))
  res.end()
}
```

Request to `/api/users/123` will have `req.params.id === "123"`.

### Auto-Building API Folder

If you have an `api` folder in your repository root, Stormkit automatically builds and deploys it to `.stormkit/api`.

To disable auto-building:

```bash theme={null}
SK_BUILD_API=off
```

Set this environment variable in your configuration.

## Build Process

The complete build process follows these steps:

<Steps>
  <Step title="Repository Clone">
    Runner clones your repository at the specified branch and commit.
  </Step>

  <Step title="Runtime Installation">
    Installs required runtimes (Node.js, Go, etc.) using mise based on version files.
  </Step>

  <Step title="Dependency Installation">
    Runs package manager install command (`npm install`, `yarn`, `pnpm install`, etc.).
  </Step>

  <Step title="Build Command">
    Executes your configured build command with environment variables.
  </Step>

  <Step title="API Auto-Build">
    If an `api` folder exists, automatically builds and transpiles it.
  </Step>

  <Step title="Artifact Bundling">
    Identifies static, server, and API folders. Bundles required dependencies.
  </Step>

  <Step title="Compression">
    Creates zip files for each artifact type (client.zip, server.zip, api.zip).
  </Step>

  <Step title="Upload">
    Uploads artifacts to S3 and configures Lambda functions.
  </Step>
</Steps>

## Deployment Artifacts

Each deployment creates the following artifacts:

### Client Zip

Contains all static files from the `public` folder(s).

**Included**:

* HTML files
* CSS files
* JavaScript bundles
* Images and fonts
* Any static assets

### Server Zip

Contains server-side code and dependencies.

**Included**:

* Entry file (index.js, server.js, etc.)
* Bundled node\_modules dependencies
* Server-side code and templates

### API Zip

Contains API functions and dependencies.

**Included**:

* API route files
* Stormkit API wrapper (stormkit-api.mjs)
* Bundled node\_modules dependencies

## Example Deployment

Here's a complete example of a React app with API:

### Repository Structure

```bash theme={null}
my-app/
├── src/
│   ├── App.tsx
│   └── index.tsx
├── api/
│   ├── hello.ts
│   └── users.ts
├── package.json
└── vite.config.ts
```

### Build Configuration

```typescript vite.config.ts theme={null}
import { defineConfig } from 'vite'

export default defineConfig({
  build: {
    outDir: '.stormkit/public'
  }
})
```

### Deployment Result

```bash theme={null}
.stormkit/
├── public/              # Vite build output
│   ├── index.html
│   └── assets/
│       ├── index-abc123.js
│       └── index-def456.css
└── api/                 # Auto-built from /api
    ├── hello.js
    ├── users.js
    └── node_modules/
```

## Starter Template

Check out the [React Starter Template](https://github.com/stormkit-io/monorepo-template-react) to see a complete example with the correct `.stormkit` folder structure.

## Related Documentation

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/deployments/configuration">
    Configure output folders and build settings
  </Card>

  <Card title="Application Runtime" icon="server" href="/deployments/application-runtime">
    Run long-running server processes
  </Card>

  <Card title="Writing API" icon="code" href="/features/writing-api">
    Complete guide to API functions
  </Card>

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