= Vertx.x Starter

image:https://github.com/vert-x3/vertx-starter/workflows/CI/badge.svg[Build Status,link=https://github.com/vert-x3/vertx-starter/actions?query=workflow%3ACI]

https://start.vertx.io[Vert.x Starter] is an open-source web application for creating https://vertx.io/[Vert.x] applications.

== Quickstart

Simply click on Generate Project on the web interface to download a project archive.

If you are a CLI adept, you can use any http client (curl, https://httpie.org/[httpie]) to invoke the API.

[source,shell,subs="attributes"]

curl -G https://start.vertx.io/starter.zip \ -d "groupId=com.example" \ -d "language=java" \ --output starter.zip

== API

== Generating a Vert.x application

https://start.vertx.io/starter.{archiveFormat}

NOTE: archiveFormat can be zip, tgz, tar.gz, etc. if the project generator can handle the format, it will use the appropriate compression tool.

You can provide the following query parameters to customize the project:

• Basic information for the generated project groupId, artifactId
• language: java or kotlin
• buildTool: maven or gradle build tool
• vertxVersion: the Vert.x version
• vertxDependencies: a comma separated list of artifactIds of the vert.x modules
• packageName: code package name, derived from groupId and artifactId by default
• jdkVersion: which version of the JDK to use, defaults to 11

Full example:

[source,shell,subs="attributes"]

curl -G https://start.vertx.io/starter.zip \ -d "groupId=com.example" \ -d "artifactId=starter" \ -d "language=java" \ -d "buildTool=maven" \ -d "vertxDependencies=vertx-web,vertx-web-client" --output starter.zip

The HTTPie equivalent:

[source,shell,subs="attributes"]

http https://start.vertx.io/starter.zip \ groupId==com.example \ artitfactId==starter \ language==java \ buildTool==maven \ vertxDependencies==vertx-web,vertx-web-client \ -o starter.zip

== Vert.x Starter metadata

The vert.x starter metadata lists all the capabilities proposed by the API. The metadata is used to build the Web UI is exposed to ease the creation of third-party clients (IDE integration, CLI, etc).

https://start.vertx.io/metadata

== Running your own starter

=== Building fat jar

In order to build it, you will need Java 17.

[source,shell]

./mvnw clean package -DskipTests

=== Running the app locally

[source,shell]

Configure analytics dir

export VERTX_STARTER_ANALYTICS_DIR=target

Build frontend first

./mvnw clean process-resources

Run backend in redeploy mode

./mvnw compile vertx:run -Dskip.npm

=== Running frontend in development mode

[source,shell]

cd src/main/frontend npm run dev

NOTE: The frontend development server expects the backend to listen on localhost port 8080.

== Releasing

NOTE: The following commands assume you have forked the project and upstream is the vert-x3/vertx-starter remote repository.

To release the project, proceed as follows.

First, tag the last commit in master branch:

[source,shell]

STARTER_VERSION=$(./mvnw org.apache.maven.plugins:maven-help-plugin:evaluate -Dexpression=project.version -B | grep -v '[') git tag -f -a ${STARTER_VERSION} -m "Version ${STARTER_VERSION}" git push upstream --tags

Close the corresponding https://github.com/vert-x3/vertx-starter/milestones[milestone] on GitHub.

Then merge the master branch into the prod branch:

[source,shell]

git checkout prod git pull git merge master git push

GitHub Deploy job will automatically redeploy the starter if the prod branch build passes.

Eventually, checkout master again and update the version:

[source,shell]

git checkout master ./mvnw versions:set -DgenerateBackupPoms=false git add pom.xml git commit -s git push upstream && git push

== License

Vert.x Starter is Open Source software released under the https://www.apache.org/licenses/LICENSE-2.0.html[Apache 2.0 license].