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:

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

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

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

.stormkit/server/index.js

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:

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:

package.json

{
  "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:

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

.stormkit/api/hello.js

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()
}

API functions don’t need the serverless wrapper. Stormkit handles the wrapper automatically for API routes.

Dynamic Routes

Use bracket notation for dynamic parameters:

.stormkit/api/users/[id].js

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:

SK_BUILD_API=off

Set this environment variable in your configuration.

Build Process

The complete build process follows these steps:

1. Repository Clone

   Runner clones your repository at the specified branch and commit.

2. Runtime Installation

   Installs required runtimes (Node.js, Go, etc.) using mise based on version files.

3. Dependency Installation

   Runs package manager install command (npm install, yarn, pnpm install, etc.).

4. Build Command

   Executes your configured build command with environment variables.

5. API Auto-Build

   If an api folder exists, automatically builds and transpiles it.

6. Artifact Bundling

   Identifies static, server, and API folders. Bundles required dependencies.

7. Compression

   Creates zip files for each artifact type (client.zip, server.zip, api.zip).

8. Upload

   Uploads artifacts to S3 and configures Lambda functions.

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

my-app/
├── src/
│   ├── App.tsx
│   └── index.tsx
├── api/
│   ├── hello.ts
│   └── users.ts
├── package.json
└── vite.config.ts

Build Configuration

vite.config.ts

import { defineConfig } from 'vite'

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

Deployment Result

.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 to see a complete example with the correct .stormkit folder structure.

Related Documentation

Configuration

Configure output folders and build settings

Application Runtime

Run long-running server processes

Writing API

Complete guide to API functions

Troubleshooting

Fix common deployment issues