create-teavm-app

create-teavm-app

CLI tool that scaffolds a full-stack TeaVM + Cloud Run + Firebase application in a single command.

Quick Start

npx create-teavm-app \
  --name my-cool-app \
  --package ca.weblite.mycoolapp \
  --description "My cool application" \
  --database \
  --auth

Installation

Via npm/npx (recommended — jdeploy handles JRE download automatically):

npx create-teavm-app --name my-app --package com.example.myapp

Or build from source:

mvn clean package
java -jar target/create-teavm-app-0.1.0.jar --name my-app --package com.example.myapp

CLI Parameters

Required

Parameter	Short	Description
--name	-n	App name in kebab-case (e.g. my-cool-app)
--package	-p	Java package (e.g. ca.weblite.mycoolapp)

Optional

Parameter	Short	Default	Description
--description	-d	"A TeaVM application"	One-line description for POM and CLAUDE.md
--group-id	-g	Derived from package	Maven group ID
--output-dir	-o	.	Where to create the project directory
--database / --no-database		true	Include PostgreSQL database support (Cloud SQL)
--auth / --no-auth		true	Include Firebase Auth / JWT validation
--object-store		false	Include R2/S3 object storage
--messaging		false	Include Pub/Sub messaging
--processor		(none)	Repeatable. Processor service name (implies --messaging)
--teavm-lambda-version		0.1.5	teavm-lambda version
--teavm-react-version		0.1.2	teavm-react version
--teavm-version		0.13.1	TeaVM compiler version
--skip-frontend		false	Skip generating the frontend module
--skip-workflows		false	Skip generating GitHub Actions workflows

Generated Project Structure

For --name my-app --package ca.weblite.myapp:

my-app/
├── pom.xml                          # Parent POM with dependencyManagement
├── mvnw / mvnw.cmd                  # Maven wrapper
├── .mvn/settings.xml                # GitHub Packages auth
├── .tool-versions                   # asdf: java, maven, nodejs
├── .gitignore
├── CLAUDE.md                        # Project docs for Claude Code
├── dev.sh                           # Local dev script
├── setup-local.sh                   # First-time setup
├── docker-compose.yml               # PostgreSQL, MinIO, Pub/Sub as needed
│
├── my-app-common/                   # Shared models and interfaces
│   ├── pom.xml
│   └── src/.../common/package-info.java
│
├── my-app-api/                      # Backend API service
│   ├── pom.xml                      # teavm & jvm profiles
│   ├── run-tests.sh
│   ├── docker/                      # Dockerfile, server.js, init.sql
│   └── src/.../api/
│       ├── Main.java                # GeneratedContainer, GeneratedRouter, Platform.start()
│       └── HealthResource.java      # @Path("/health") @Component @Singleton @PermitAll
│
├── my-app-frontend/                 # Frontend SPA (unless --skip-frontend)
│   ├── pom.xml                      # teavm.version=0.13.1, teavm-react-core
│   ├── firebase.json
│   ├── docker/                      # Dockerfile, nginx.conf
│   ├── src/main/webapp/index.html
│   └── src/.../frontend/App.java    # ReactDOM.createRoot, React.wrapComponent
│
├── my-app-{processor}/              # For each --processor
│   ├── pom.xml
│   ├── docker/
│   └── src/.../{processor}/
│       ├── Main.java
│       ├── ProcessResource.java     # @Path("/process") @POST
│       └── HealthResource.java
│
├── docker/pubsub-bridge/            # If --messaging
│
└── .github/workflows/               # Unless --skip-workflows
    ├── ci.yml
    ├── deploy-staging.yml
    └── deploy-prod.yml

Examples

Full-featured app with all defaults:

npx create-teavm-app -n my-app -p ca.weblite.myapp

Minimal API-only app:

npx create-teavm-app \
  --name my-api \
  --package ca.weblite.myapi \
  --no-database --no-auth \
  --skip-frontend --skip-workflows

App with object storage and a processor:

npx create-teavm-app \
  --name media-app \
  --package ca.weblite.mediaapp \
  --object-store \
  --processor image-processor

Development

Prerequisites

• Java 21
• Maven 3.9+

Build

mvn clean package

Test

mvn test

The test suite includes 24 integration tests covering all flag combinations, generated file content verification, and template engine unit tests.

Tech Stack

• Java 21 with Picocli for CLI argument parsing
• maven-shade-plugin for uber JAR packaging
• jdeploy for npm distribution (npx support)
• Template-based generation with {{PLACEHOLDER}} substitution and {{#CONDITION}}/{{^CONDITION}} conditional blocks