Extension codestart

Create the runtime/src/main/codestarts/quarkus/aloha-codestart directory

Move the src/main/java from your generated project to runtime/src/main/codestarts/quarkus/aloha-codestart/java/src/main/java

(Optional) Move the config using this convention: application config application.yml.

Create a codestart.yml file in runtime/src/main/codestarts/quarkus/aloha-codestart:

name: aloha-codestart
ref: aloha
type: code
tags: extension-codestart
metadata:
  title: Aloha
  description: Start to code with the Aloha extension.
  related-guide-section: https://docs.quarkiverse.io/quarkus-aloha/dev/
  path: /aloha # (optional) for web extensions providing HTTP resources

Add the Maven build plugin configuration in runtime/pom.xml (to generate the codestart artifact: /target/quarkus-aloha-VERSION-codestarts.jar):

      <plugin>
        <artifactId>maven-jar-plugin</artifactId>
        <executions>
          <execution>
            <id>generate-codestart-jar</id>
            <phase>generate-resources</phase>
            <goals>
              <goal>jar</goal>
            </goals>
            <configuration>
              <classesDirectory>${project.basedir}/src/main</classesDirectory>
              <includes>
                <include>codestarts/**</include>
              </includes>
              <classifier>codestarts</classifier>
              <skipIfEmpty>true</skipIfEmpty>
            </configuration>
          </execution>
        </executions>
      </plugin>

Add the codestart binding in the extension metadata runtime/src/main/resources/META-INF/quarkus-extension.yaml. Without this, your codestart won’t be added when your extension is picked:

name: ...
description: ...
metadata:
  ...
  codestart:
    name: "aloha"
    languages:
    - "java"
    artifact: "io.quarkiverse.aloha:quarkus-aloha:codestarts:jar:${project.version}"

Add the readme README.md section template in base/README.tpl.qute.md:

{#include readme-header /}

Run mvn clean install in the extension root (or just runtime).

Now we can check that the codestart actually works by creating a project consuming our extension (make sure the snapshot version is correct):

quarkus create app aloha-app -x=io.quarkiverse.aloha:quarkus-aloha:999-SNAPSHOT

...
applying codestarts...
📚  java
🔨  maven
📦  quarkus
📝  config-properties
🔧  dockerfiles
🔧  maven-wrapper
🚀  aloha-codestart <<<<<<<<<<<<<<<<
...

Add this dependency to the integration-tests:

<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-devtools-testing</artifactId>
  <scope>test</scope>
</dependency>

Create a AlohaCodestartTest in the integration-tests:

public class AlohaCodestartTest {

    @RegisterExtension
    public static QuarkusCodestartTest codestartTest = QuarkusCodestartTest.builder()
            .languages(Language.JAVA)
            .setupStandaloneExtensionTest("io.quarkiverse.aloha:quarkus-aloha")
            .build();

    @Test
    void testContent() throws Throwable {
        codestartTest.checkGeneratedSource("org.acme.AlohaResource");
    }

    @Test
    void buildAllProjects() throws Throwable {
        codestartTest.buildAllProjects();
    }
}

If the extension provides some web resources, add the base/src/main/resources/META-INF/resources/index.entry.qute.html template (index.html and web extension codestarts).

Add another language (it is recommended to provide Java and Kotlin).

You may add some other resources (in the ./base directory if they are not language-specific).

The codestarts are all grouped in a specific module.

No extra Maven configuration is needed.

The extension metadata references the artifact containing all the core codestarts.

The tests are also grouped. You don’t need to test the build as there is a specific grouped test for it. e.g.:

public class ConfigYamlCodestartTest {

    @RegisterExtension
    public static QuarkusCodestartTest codestartTest = QuarkusCodestartTest.builder()
            .codestarts("config-yaml")
            .languages(JAVA, KOTLIN)
            .build();

    @Test
    void testContent() throws Throwable {
        codestartTest.checkGeneratedSource("org.acme.GreetingConfig");
        codestartTest.assertThatGeneratedFileMatchSnapshot(JAVA, "src/main/resources/application.yml");
    }

    @Test
    @EnabledIfSystemProperty(named = "build-projects", matches = "true")
    void buildAllProjectsForLocalUse() throws Throwable {
        codestartTest.buildAllProjects();
    }

}

codestart.yml must be at the root of the codestart

./base contains all the files that will be processed independently of the specified language

./[java/kotlin/scala] contains all the files that will be processed only if the specified language has been selected (overriding base)

.tpl.qute will be processed with Qute and can use data (.tpl.qute will be removed from the output file name).

certain common files, such as readme.md, src/main/resources/application.yml, src/main/resources/META-INF/resources/index.html are generated from the collected fragments found in the selected codestarts for the project

other files are copied.

The data (and public metadata) of the codestart to generate (specified in the codestart.yml)

A merge of the shared-data from the all the codestarts used to generate the project

The user input

Some dynamically generated data (e.g. dependencies and test-dependencies)

merged with the other extension codestarts configs

automatically converted to the selected config type (yaml or properties) at generation time depending on the selected extensions

the generated project content (with immutable mocked data) using snapshot testing

the generated project build/run (with real data) with helpers to run the build

Your extension codestart must/should be independent of buildtool and dockerfiles.

Extension codestarts should be able to work alongside each other without interference (in combination).

Make sure your class names are unique across all extension codestarts.

Only use org.acme as package name.

Use a unique path /[unique] for your REST paths

Write the config in yml src/main/resources/application.yml.

You can start with java and add kotlin later in another PR (create an issue so you don’t forget).

If you have a question, ping me @ia3andy on https://quarkusio.zulipchat.com/.