Serverless Hosting Guide

Complete reference for building and deploying applications on Hiveku’s serverless infrastructure.

Platform: AWS Lambda + CloudFront + S3 | Runtime: Node.js 20.x on ARM64 | Not supported: PHP, WebSockets, native modules without layers, persistent processes

Architecture

Static assets are built and uploaded to S3, served via CloudFront CDN (global edge locations)
Automatic HTTPS with wildcard certificate
URL rewriting for clean routes (/about → /about/index.html)
Cache: HTML 1 min, CSS/JS 5 min
Each API route becomes a Lambda function with its own URL
SSR pages are bundled with the server runtime

Resource Limits

Resource	Default	Maximum	Notes
Memory	256 MB	10,240 MB	Higher memory = faster CPU
Timeout	30 seconds	900 seconds (15 min)	SSR uses 60s default
Bundle Size (zipped)	-	50 MB	Larger uses S3 upload
Bundle Size (unzipped)	-	250 MB	AWS Lambda hard limit
Request Payload	-	6 MB	Use S3 presigned URLs for larger
Response Payload	-	6 MB	Stream large responses
Ephemeral Storage (/tmp)	512 MB	10,240 MB	Cleared between invocations
Environment Variables	-	4 KB total	Use Secrets Manager for large
Concurrent Executions	1,000	Depends on quota	Per-account AWS limit
ZIP Import (upload)	-	1 GB	Max 10,000 files

Do’s and Don’ts

Do
Don't

Use pure JavaScript packages — bcryptjs, pg (pure mode), jose for JWT
Keep functions small — split large APIs into separate files for faster cold starts
Use environment variables — store secrets in Hiveku’s env vars, not in code
Optimize bundle size — use dynamic imports, tree-shaking, avoid bundling dev deps
Use S3 for large files — generate presigned URLs for uploads over 6MB
Return proper status codes — use 200, 201, 400, 401, 404, 500 appropriately
Set cache headers — use Cache-Control for static responses
Handle cold starts — initialize DB connections outside the handler

Manually bundle native modules — bcrypt, sharp, canvas won’t work without layers
Rely on filesystem persistence — Lambda /tmp is ephemeral (cleared between invocations)
Use setTimeout for cron jobs — functions terminate after response, timers don’t persist
Run long background jobs — max timeout is 15 minutes, no background threads
Bundle large files in functions — ML models, large datasets increase cold start
Hardcode credentials — secrets in code are exposed in logs and bundles

API Routes

Where to Place API Files

Hiveku auto-detects API routes from these directories:

# Standard locations
api/
src/api/
functions/
lambdas/
serverless/

# Next.js App Router
app/api/**/route.ts

# Next.js Pages Router
pages/api/**/*.ts

File to URL Mapping

File Path	Deployed URL
`api/users.ts`	`/api/users`
`api/users/[id].ts`	`/api/users/:id`
`api/files/[...path].ts`	`/api/files/*` (catch-all)
`app/api/auth/route.ts`	`/api/auth`

API Handler Formats

Hiveku supports two function formats — use whichever you prefer:

Web API Format (Recommended)
AWS Lambda Format

Modern format, similar to Next.js/Vercel Edge Functions:

// api/users.ts
export default async function handler(req: Request) {
  // req.method - GET, POST, PUT, DELETE, PATCH
  // req.url - Full URL with query params
  // req.headers - Headers object (lowercase keys)
  // req.body - Parsed JSON body
  // req.query - Query parameters object
  // req.params - URL path parameters (e.g., [id])
  
  if (req.method === 'GET') {
    return Response.json({ users: [] });
  }
  
  if (req.method === 'POST') {
    const body = await req.json();
    return Response.json({ created: body }, { status: 201 });
  }
  
  return Response.json({ error: 'Method not allowed' }, { status: 405 });
}

Traditional format, compatible with Netlify Functions, Vercel (legacy), AWS SAM:

// api/users.ts
export async function handler(event: any) {
  const headers = {
    'Content-Type': 'application/json',
    'Access-Control-Allow-Origin': '*',
  };

  if (event.httpMethod === 'OPTIONS') {
    return { statusCode: 200, headers, body: '' };
  }

  if (event.httpMethod === 'GET') {
    return {
      statusCode: 200,
      headers,
      body: JSON.stringify({ users: [] })
    };
  }

  return {
    statusCode: 405,
    headers,
    body: JSON.stringify({ error: 'Method not allowed' })
  };
}

Feature	Web API Format	AWS Lambda Format
Export	`export default function`	`export async function handler`
HTTP Method	`req.method`	`event.httpMethod`
Query Params	`req.query.id`	`event.queryStringParameters?.id`
Request Body	`req.body` (auto-parsed)	`JSON.parse(event.body)`
Response	`Response.json(data)`	`{ statusCode, body, headers }`

hiveku.json Configuration

Create a hiveku.json in your project root to customize deployment:

{
  "functions": {
    "directories": ["api/", "src/lambdas/"],
    "include": ["lib/scheduled-job.ts"],
    "exclude": ["api/internal/**", "**/*.test.ts"],
    "routes": {
      "api/legacy-auth.ts": "/api/v1/auth",
      "api/new-auth.ts": "/api/v2/auth"
    },
    "config": {
      "api/image-processor.ts": {
        "memory": 1024,
        "timeout": 120
      },
      "api/heavy-compute.ts": {
        "memory": 2048,
        "timeout": 300
      },
      "**": {
        "memory": 256,
        "timeout": 30
      }
    }
  },
  "build": {
    "outputDirectory": "dist",
    "env": {
      "NEXT_PUBLIC_API_URL": "https://api.example.com"
    }
  }
}

Field	Description
`functions.directories`	Additional directories to scan for API routes
`functions.include`	Specific files to include as functions
`functions.exclude`	Glob patterns to exclude
`functions.routes`	Override auto-generated URL paths
`functions.config`	Per-function memory/timeout settings. Use `**` for defaults
`build.outputDirectory`	Custom build output directory
`build.env`	Build-time environment variables (`NEXT_PUBLIC_*`)

Advanced Features

Lambda Layers

Auto-provisioned layers for native dependencies. These packages just work when you add the layer: sharp bcrypt argon2 canvas prisma ffmpeg puppeteer

Scheduled Functions (Cron)

Add a @schedule comment or put files in a cron/ directory:

// api/cron/daily-report.ts
// @schedule cron(0 9 * * ? *)

export default async function() {
  const report = await generateReport();
  await sendEmail(report);
  return { success: true };
}

Cron format: cron(min hour day-of-month month day-of-week year)

Expression	Description
`cron(0 9 * * ? *)`	9 AM daily
`cron(0 /2 * ? *)`	Every 2 hours
`cron(0 9 ? * MON-FRI *)`	9 AM weekdays
`cron(0 0 1 * ? *)`	1st of month

Rate format: rate(5 minutes), rate(1 hour), rate(1 day), rate(7 days)

Streaming Responses

SSE and chunked responses for AI apps. Auto-detected from text/event-stream content type:

// api/stream/ai-chat.ts
// @streaming

export default async function(req: Request) {
  const { prompt } = await req.json();
  
  return new Response(
    new ReadableStream({
      async start(controller) {
        for await (const chunk of streamAI(prompt)) {
          controller.enqueue(`data: ${JSON.stringify(chunk)}\n\n`);
        }
        controller.close();
      }
    }),
    { headers: { 'Content-Type': 'text/event-stream' } }
  );
}

Package Compatibility

Works
Needs Replacement
Next.js Only

Package	Use For
`prisma`	ORM (use connection pooling + keep-alive for serverless)
`pg` / `mysql2`	Database drivers (pure JS mode)
`bcryptjs`	Password hashing (pure JS)
`jose`	JWT signing/verification
`zod`	Schema validation
`axios` / `node-fetch`	HTTP clients
`@aws-sdk/*`	AWS services (S3, SES, etc.)
`stripe`	Payment processing
`resend` / `nodemailer`	Email sending
`openai`	AI/LLM integration

Package	Replace With
`bcrypt`	`bcryptjs`
`jsonwebtoken`	`jose` (pure JS)
`sharp`	`jimp` or Lambda Layer
`canvas`	Lambda Layer
`sqlite3`	Supabase, PlanetScale, Turso
`pg-native`	`pg` (pure JS mode)
`puppeteer`	`@sparticuz/chromium` Layer
`grpc`	`connect-web` (gRPC-Web)

These packages only work in Next.js and need alternatives in Vite/React:

Package	Alternative
`next-themes`	CSS `prefers-color-scheme` or custom ThemeProvider
`next/image`	Standard `<img>` tags or a Vite image plugin
`next/font`	`@fontsource` packages or Google Fonts CDN
`next/link`	`react-router-dom` Link

Code Patterns

Database Connection (Prisma)

Initialize the Prisma client outside the handler so connections are reused across Lambda invocations. Use connection pooling and keep-alive pings to avoid cold reconnect latency.

// lib/prisma.ts
import { PrismaClient } from '@prisma/client';

const globalForPrisma = globalThis as unknown as {
  prisma: PrismaClient | undefined;
  connectionWarmed: boolean;
  keepAliveInterval: NodeJS.Timeout | undefined;
};

export const prisma =
  globalForPrisma.prisma ??
  new PrismaClient({
    log: process.env.NODE_ENV === 'development' ? ['error', 'warn'] : ['error'],
    datasources: {
      db: { url: process.env.DATABASE_URL },
    },
  });

if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;

// Pre-warm the connection on cold start (reduces first query latency)
if (!globalForPrisma.connectionWarmed) {
  globalForPrisma.connectionWarmed = true;
  prisma.$queryRaw`SELECT 1`.catch(() => {});
}

// Keep-alive: ping every 20s to prevent connection pool from closing
// Supabase session pooler closes idle connections after ~30 seconds
if (process.env.NODE_ENV === 'production' && !globalForPrisma.keepAliveInterval) {
  globalForPrisma.keepAliveInterval = setInterval(async () => {
    try { await prisma.$queryRaw`SELECT 1`; } catch {}
  }, 20000);
  globalForPrisma.keepAliveInterval.unref?.();
}

export default prisma;

Set connection_limit and pool_timeout in your DATABASE_URL query string. A limit of 10-15 connections with a 30s timeout works well for serverless.

JWT Authentication

Use the jose library for JWT — it’s pure JavaScript and works on Lambda. Avoid jsonwebtoken as it has native dependencies.

// lib/auth.ts
import { SignJWT, jwtVerify } from 'jose';

const secret = new TextEncoder().encode(process.env.JWT_SECRET);

export async function signToken(payload: { userId: string; email: string }) {
  return await new SignJWT(payload)
    .setProtectedHeader({ alg: 'HS256' })
    .setIssuedAt()
    .setExpirationTime('7d')
    .sign(secret);
}

export async function verifyToken(token: string) {
  try {
    const { payload } = await jwtVerify(token, secret);
    return payload as { userId: string; email: string };
  } catch {
    return null;
  }
}

// api/protected.ts - Protected route example
import { verifyToken } from '../lib/auth';

export default async function handler(req: Request) {
  // Headers are lowercase on Lambda!
  const authHeader = req.headers.get('authorization');
  if (!authHeader?.startsWith('Bearer ')) {
    return Response.json({ error: 'Missing token' }, { status: 401 });
  }
  
  const payload = await verifyToken(authHeader.slice(7));
  if (!payload) {
    return Response.json({ error: 'Invalid token' }, { status: 401 });
  }
  
  return Response.json({ message: 'Authenticated!', user: payload });
}

Large File Upload (S3 Presigned URL)

// api/upload-url.ts
import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';

const s3 = new S3Client({ region: process.env.AWS_REGION });

export default async function handler(req: Request) {
  const { filename, contentType } = await req.json();
  
  const command = new PutObjectCommand({
    Bucket: process.env.S3_BUCKET,
    Key: `uploads/${Date.now()}-${filename}`,
    ContentType: contentType,
  });
  
  const uploadUrl = await getSignedUrl(s3, command, { expiresIn: 3600 });
  return Response.json({ uploadUrl });
}

Custom CORS Headers

// api/data.ts
export default async function handler(req: Request) {
  const headers = {
    'Access-Control-Allow-Origin': 'https://myapp.com',
    'Access-Control-Allow-Methods': 'GET, POST',
    'Access-Control-Allow-Headers': 'Content-Type, Authorization',
  };
  
  if (req.method === 'OPTIONS') {
    return new Response(null, { status: 204, headers });
  }
  
  return Response.json({ data: 'hello' }, { headers });
}

Reusable Auth Middleware

// lib/withAuth.ts
import { verifyToken } from './auth';

type AuthenticatedHandler = (
  req: Request,
  user: { userId: string; email: string }
) => Promise<Response>;

export function withAuth(handler: AuthenticatedHandler) {
  return async (req: Request): Promise<Response> => {
    const authHeader = req.headers.get('authorization');
    if (!authHeader?.startsWith('Bearer ')) {
      return Response.json({ error: 'Missing Authorization header' }, { status: 401 });
    }
    
    const user = await verifyToken(authHeader.slice(7));
    if (!user) {
      return Response.json({ error: 'Invalid or expired token' }, { status: 401 });
    }
    
    return handler(req, user);
  };
}

// api/profile.ts - Using the middleware
import { withAuth } from '../lib/withAuth';

export default withAuth(async (req, user) => {
  const profile = await prisma.user.findUnique({
    where: { id: user.userId },
    select: { id: true, email: true, name: true }
  });
  return Response.json(profile);
});

Environment Variables

Auto-Injected Variables

These are available in every Lambda function automatically:

NODE_ENV=production
AWS_REGION=us-east-1
HIVEKU_PROJECT_ID=your-project-id
DATABASE_URL=... (if provisioned)

Build-Time vs Runtime

NEXT_PUBLIC_* variables are bundled at build time and exposed to the browser
All other variables are available only at runtime, server-side only

NEXT_PUBLIC_* variables require a redeploy to take effect after changes.

Troubleshooting

Function timeout (30s limit)

Check if you’re hitting the 30s default timeout. Increase in hiveku.json, or optimize your code. Database queries without connection pooling are a common cause.

Bundle too large

Use dynamic imports, check for accidentally bundled devDependencies, exclude large assets. Consider splitting into multiple functions.

Native module error

You’re using a package with native bindings (bcrypt, sharp, etc.). Switch to a pure JS alternative or request a Lambda Layer.

CORS errors

Hiveku adds CORS headers automatically. If you still see errors, check your frontend is calling the correct URL and your API returns proper response format.

Environment variable undefined

Make sure the variable is set in Hiveku dashboard. NEXT_PUBLIC_* vars need a redeploy to take effect. Server-side vars are only available in Lambda, not the browser.

Slow cold starts

Reduce bundle size, increase memory (more memory = faster CPU), minimize top-level imports. Consider keeping functions warm with scheduled pings.

Too many database connections

Lambda can scale to many instances. Use a connection pooler (Supabase, PlanetScale) or set your pool size to 1-2 connections per function.

Files disappear from /tmp

Lambda /tmp is ephemeral. Files may persist between invocations on the same instance but will be cleared. Use S3 for persistent storage.

Get Started

AI Assistant

Code Editor

Publishing

Integrations

Account & Settings

Architecture

Resource Limits

Do’s and Don’ts

API Routes

Where to Place API Files

File to URL Mapping

API Handler Formats

hiveku.json Configuration

Advanced Features

Lambda Layers

Scheduled Functions (Cron)

Streaming Responses

Package Compatibility

Code Patterns

Database Connection (Prisma)

JWT Authentication

Large File Upload (S3 Presigned URL)

Custom CORS Headers

Reusable Auth Middleware

Environment Variables

Auto-Injected Variables

Build-Time vs Runtime

Troubleshooting

Get Started

AI Assistant

Code Editor

Publishing

Integrations

Account & Settings

​Architecture

​Resource Limits

​Do’s and Don’ts

​API Routes

​Where to Place API Files

​File to URL Mapping

​API Handler Formats

​hiveku.json Configuration

​Advanced Features

​Lambda Layers

​Scheduled Functions (Cron)

​Streaming Responses

​Package Compatibility

​Code Patterns

​Database Connection (Prisma)

​JWT Authentication

​Large File Upload (S3 Presigned URL)

​Custom CORS Headers

​Reusable Auth Middleware

​Environment Variables

​Auto-Injected Variables

​Build-Time vs Runtime

​Troubleshooting

Architecture

Resource Limits

Do’s and Don’ts

API Routes

Where to Place API Files

File to URL Mapping

API Handler Formats

hiveku.json Configuration

Advanced Features

Lambda Layers

Scheduled Functions (Cron)

Streaming Responses

Package Compatibility

Code Patterns

Database Connection (Prisma)

JWT Authentication

Large File Upload (S3 Presigned URL)

Custom CORS Headers

Reusable Auth Middleware

Environment Variables

Auto-Injected Variables

Build-Time vs Runtime

Troubleshooting