Skip to main content
Compile JavaScript Lambda functions to optimized deployment packages (.zip) ready for AWS Lambda.

​
Usage

porf lambda [flags] handler.js function.zip

​
Examples

porf lambda handler.js function.zip

​
Arguments

​
handler.js
string
required
JavaScript Lambda handler file (must export handler function)
​
function.zip
string
required
Output deployment package (.zip file)

​
Handler Function

Your Lambda handler file must export a handler function:
handler.js
export const handler = async (event, context) => {
  // Process event
  return {
    statusCode: 200,
    body: JSON.stringify({ message: 'Hello from Porffor!' })
  };
};
Porffor automatically removes the async keyword as it compiles synchronous code. The handler is internally wrapped to support Lambda’s requirements.

​
Compilation Process

The Lambda compilation:
  1. Wraps handler: Converts async handler to Porffor-compatible format
  2. Compiles to C: Uses 2c to generate C source code
  3. Compiles to native: Produces bootstrap executable
  4. Creates package: Packages bootstrap into .zip file
$ porf lambda handler.js function.zip
Compiling handler.js to AWS Lambda function...
compiled in 234.56ms
Lambda function packaged to function.zip

​
Optimizations

​
-On
flag
Porffor optimization level
porf lambda -O3 handler.js function.zip
​
-d
flag
Debug mode - includes symbols, disables stripping
porf lambda -d handler.js function-debug.zip
Debug packages:
  • Include function names and debug info
  • Are larger in size
  • Easier to troubleshoot
  • Should not be used in production

​
Compiler Selection

Lambda compilation uses a C compiler. By default:
  1. Checks for musl-gcc (recommended)
  2. Falls back to gcc if musl-gcc not found
  3. Can be overridden with CC environment variable
​
CC
environment
Override C compiler
CC=musl-gcc porf lambda handler.js function.zip
CC=gcc porf lambda handler.js function.zip

​
Installing musl-gcc

musl-gcc is recommended for Lambda as it noticeably improves deployed performance.
sudo apt install musl-tools

​
Lambda Configuration

Porffor uses optimized settings for Lambda:
  • Allocator: oneshot (faster cold starts)
  • Target: c (via 2c compiler)
  • Architecture: x86_64-v3 optimized
  • Stripping: Enabled (unless -d flag)
  • Static linking: Enabled with musl-gcc

​
Package Contents

The generated .zip contains: 
function.zip
└── bootstrap          # Native executable
The bootstrap file is the Lambda custom runtime executable.

​
Deployment

1

Upload to Lambda

aws lambda create-function \
  --function-name my-porffor-function \
  --runtime provided.al2023 \
  --handler bootstrap \
  --zip-file fileb://function.zip \
  --role arn:aws:iam::ACCOUNT:role/lambda-role
2

Configure runtime

Use provided.al2023 or provided.al2 runtime
aws lambda update-function-configuration \
  --function-name my-porffor-function \
  --runtime provided.al2023
3

Test invocation

aws lambda invoke \
  --function-name my-porffor-function \
  --payload '{"key": "value"}' \
  response.json

​
Return Values

The handler must return either:
  1. Object - Automatically JSON stringified 
    return { statusCode: 200, body: 'OK' };
  2. Bytestring - Returned as-is 
    return JSON.stringify({ message: 'Hello' });

​
Complete Example

export const handler = async (event) => {
  console.log('Event:', JSON.stringify(event));
  
  return {
    statusCode: 200,
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      message: 'Hello from Porffor Lambda!',
      input: event
    })
  };
};

​
Package Size

Optimized Lambda packages are typically:
  • Simple handler: 50-100 KB
  • Medium complexity: 200-400 KB
  • Complex logic: 500 KB - 1 MB
Porffor Lambda packages are significantly smaller than typical Node.js Lambda packages because they have zero runtime dependencies.

​
Performance Benefits

  • Fast cold starts: Native executable, no runtime initialization
  • Low memory usage: No JavaScript runtime overhead
  • Predictable performance: AOT compilation, no JIT warmup
  • Small package size: No node_modules dependencies

​
Optimization Tips

# Use musl-gcc for best results
sudo apt install musl-tools

# Compile with maximum optimization
porf lambda -O3 handler.js function.zip

​
Troubleshooting

​
musl-gcc Warning

musl-gcc is recommended for Lambda as it noticeably improves 
deployed performance. Install it or explicitly specify a compiler 
via CC to hide this warning. Defaulting to gcc.
Solution: Install musl-gcc or set CC=gcc to suppress warning: 
CC=gcc porf lambda handler.js function.zip

​
Handler Not Found

Ensure your file exports handler: 
// Correct
export const handler = async (event) => { /* ... */ };

// Also works
exports.handler = async (event) => { /* ... */ };

​
Lambda Timeout

Increase timeout in AWS Lambda configuration: 
aws lambda update-function-configuration \
  --function-name my-function \
  --timeout 30

​
Missing Dependencies

Porffor has limited standard library support. Check: 
# Test locally first
porf handler.js

# Then compile to Lambda
porf lambda handler.js function.zip

​
Environment Variables

​
CC
string
C compiler to use
CC=musl-gcc porf lambda handler.js function.zip
CC=gcc porf lambda handler.js function.zip

​
Debug Mode Details

When using -d flag: 
porf lambda -d handler.js function-debug.zip
The package includes:
  • Unstripped binary with debug symbols
  • Function and variable names preserved
  • Debug compiler flags (-g, -O0)
  • C source file (.c) retained
  • Bootstrap binary retained
Debug packages are larger and slower. Only use for development.

​
AWS Lambda Runtimes

Porffor Lambda functions use custom runtimes:
  • provided.al2023 (Amazon Linux 2023) - Recommended
  • provided.al2 (Amazon Linux 2) - Also supported
  • Architecture: x86_64

​
Cleanup

By default, temporary files are removed after packaging:
  • bootstrap.c (C source)
  • bootstrap (before zipping)
With -d flag, these files are preserved for inspection.

​
Next Steps

Native Compilation

Understand the underlying native compilation

C Output

Inspect generated C code

Profile

Optimize handler performance

Run Locally

Test handler before deploying

Build docs developers (and LLMs) love

Get started for freeTalk to us