teavm-lambda

Java framework for deploying serverless functions on AWS Lambda and Google Cloud Run. Java code is compiled to JavaScript via TeaVM and runs on Node.js 22.

• JAX-RS-style annotations — @Path, @GET, @POST, @PUT, @DELETE, @PathParam, @QueryParam, @Body
• Annotation-processed router — routes are generated at compile time, zero reflection at runtime
• PostgreSQL support — async database access via the Node.js pg driver, exposed as blocking-style Java
• Static file serving (Cloud Run) — serve HTML/CSS/JS/images from src/main/webapp/ alongside your API
• Platform adapters — AWS Lambda (API Gateway) and Google Cloud Run

Prerequisites: JDK 21, Maven 3.9+, Docker, Docker Compose

mvn clean package -pl teavm-lambda-demo-cloudrun -am
cd teavm-lambda-demo-cloudrun
docker compose up

Open http://localhost:8081 to see the static web UI calling the REST API.

docker compose up -d          # start PostgreSQL
mvn clean package -pl teavm-lambda-demo -am
sam local start-api --template template.yaml
# API available at http://localhost:3001

The Cloud Run adapter automatically serves static files from a public/ directory at runtime. To add static files to your app:

1. Place files in src/main/webapp/ — HTML, CSS, JS, images, fonts, etc.

2. Add a Maven resource copy to your pom.xml:

   <execution>
       <id>copy-webapp-resources</id>
       <phase>package</phase>
       <goals><goal>copy-resources</goal></goals>
       <configuration>
           <outputDirectory>${project.build.directory}/cloudrun/public</outputDirectory>
           <resources>
               <resource>
                   <directory>${project.basedir}/src/main/webapp</directory>
               </resource>
           </resources>
       </configuration>
   </execution>

3. That's it. Requests are resolved in this order:

   • GET / → public/index.html (directory defaults)
   • GET /style.css → public/style.css (static file)
   • GET /users → Java router (API route)
   • Non-GET requests always go to the Java router

Path traversal is blocked and MIME types are detected from file extensions.

This project ships a Claude Code skill that teaches Claude how to build, deploy, and debug teavm-lambda applications. It includes API references, pom.xml templates, example projects, and common gotchas.

Download and extract the skills JAR into your project or home directory:

# Project-level (applies to this project only)
mvn dependency:copy -Dartifact=ca.weblite:teavm-lambda-parent:0.1.0-SNAPSHOT:jar:skills \
  -DoutputDirectory=/tmp/teavm-lambda-skill \
  -Dmdep.stripVersion=true
mkdir -p .claude/skills/teavm-lambda
unzip -o /tmp/teavm-lambda-skill/teavm-lambda-parent-skills.jar -d .claude/skills/teavm-lambda

# Or user-level (applies to all your projects)
mkdir -p ~/.claude/skills/teavm-lambda
unzip -o /tmp/teavm-lambda-skill/teavm-lambda-parent-skills.jar -d ~/.claude/skills/teavm-lambda

If you have the teavm-lambda repo cloned:

# Project-level
cp -r /path/to/teavm-lambda/skills/teavm-lambda .claude/skills/teavm-lambda

# Or user-level
cp -r /path/to/teavm-lambda/skills/teavm-lambda ~/.claude/skills/teavm-lambda

# Lambda demo integration tests
./teavm-lambda-demo/run-tests.sh

# Cloud Run demo integration tests
./teavm-lambda-demo-cloudrun/run-tests.sh