Maven archetypes tutorial

How to generate new projects from Maven archetypes, create your own and some alternative tools.

Archetypes

When starting a new project, it can be tedious and time-consuming to set up everything from scratch. Fortunately, Maven has built-in functionality which allows you to generate a project from a template. This template is called archetype.

There is a number of archetypes available which allow you to create various types of projects.

You can even create your own archetypes and share them with others.

Generating from command line

You can generate your project from an archetype in your command line using the following command via Maven Archetype Plugin:

mvn archetype:generate 
-DarchetypeGroupId=org.springframework.boot 
-DarchetypeArtifactId=spring-boot-sample-simple-archetype 
-DarchetypeVersion=1.0.2.RELEASE

In the example above, you specify just identifiers of your archetype and the command starts in the interactive mode and asks you for all the required information such as groupId, artifactId and version of your new project. You enter these in your terminal, and the project is generated for you.

However, you can specify all these upfront, so no interaction is needed from your side. This can be useful, for example, when generating a project as a part of some automated script which should not have any user interaction.

mvn archetype:generate 
-DarchetypeGroupId=org.springframework.boot 
-DarchetypeArtifactId=spring-boot-sample-simple-archetype 
-DarchetypeVersion=1.0.2.RELEASE 
-DartifactId=my-app -DgroupId=com.example -Dversion=1.0-SNAPSHOT -DinteractiveMode=false

Generating from IDEA

Generating projects in IDEA from archetypes is easy. Just go to:

File → New → Project... → Maven

Here all you need to do is check Create from archetype and select your desired one.

However, the amount of archetypes listed is fairly limited. Fortunately, you can add any available archetype by clicking Add archetype.

Now you can continue with creating your Maven project as usual.

Creating your own archetype

Not only you can use existing archetypes, but you can also quite easily create your own.

From an existing project

The easiest way is to have an existing project and use the Maven Archetype Plugin to generate an archetype from it. It is actually quite easy.

mvn archetype:create-from-project

The resulting archetype is generated in target/generated-sources/archetype.

Before you can use it, though, you need to install the archetype in your local repository. Just go to the directory target/generated-sources/archetype and run mvn install.

From scratch

You can actually generate your own custom archetype using a Maven archetype. This way all the scaffolding is created for you.

mvn archetype:generate
-DgroupId=my.project.group.id
-DartifactId=my-project-artifact-id
-DarchetypeGroupId=org.apache.maven.archetypes
-DarchetypeArtifactId=maven-archetype-archetype

Now all you need to do is to copy over the files which should be part of your generated project. The target location of your files is described below.

Archetype configuration

POM file

In the artifact's root directory, there is a pom.xml file of the archetype. You can see the packaging maven-archetype. You can customize build of your archetype here as with any other pom.

However, there is another pom.xml file located under src\main\resources\archetype-resources which is the pom file of the generated project. Here you can make any changes, which should be presented in the resulting project's pom.

Source code

You can put any source files, which need to be part of the output project under

src/main/resources/archetype-resources/

That is:

Java code:
src/main/resources/archetype-resources/src/main/java

Test code:
src/main/resources/archetype-resources/src/test/java

Resources:
src/main/resources/archetype-resources/src/main/resources

Archetype metadata

Each archetype contains a special XML file with the archetype configuration, which can be found under:

src/main/resources/archetype-resources/META_INF/maven/maven-metadata.xml

Here you can configure the archetype itself - for example, files which should be included, properties needed, and so on. A simple version can look something like this:

<archetype-descriptor
        xsi:schemaLocation="http://maven.apache.org/plugins/maven-archetype-plugin/archetype-descriptor/1.0.0
        http://maven.apache.org/xsd/archetype-descriptor-1.0.0.xsd"
        xmlns="http://maven.apache.org/plugins/maven-archetype-plugin/archetype-descriptor/1.0.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        name="quickstart">
    <fileSets>
        <fileSet filtered="true" packaged="true">
            <directory>src/main/java</directory>
        </fileSet>
        <fileSet>
            <directory>src/test/java</directory>
        </fileSet>
    </fileSets>
</archetype-descriptor>

You can check configuration details in the official documentation.

Alternatives

Maven archetypes are a great built-in way of generating project scaffolding. However, there are more alternatives worth exploring, which may be better suited in some cases.

Gradle

If you prefer Gradle over Maven, working with archetypes gets a little trickier because Gradle currently does not support generating projects from archetypes directly.

There is an unofficial Gradle Archetype Plugin, which you can use to work with Maven archetypes.

As an alternative, you can generate your project first using Maven from an archetype and then convert it to a Gradle project by using the following command in the directory with your pom.xml:

gradle init

Spring Boot Initializr

When working with Spring Boot, you can still use Maven archetypes, but there is a better, way more powerful tool offered directly by Spring.

It is called Spring Initializr. It is a simple wizard, where you can define many options for your application, and then it generates your project based on your choices.

You can configure various options such as:

Language: Java, Kotlin or Groovy
Spring version
Java version
Maven / Gradle
Jar/War packaging
Dependencies such as DB, Security, Web, Actuator and many more

You can see there is a lot of configuration options to choose from. Also, you can see that unlike with Maven archetypes, you can generate your project even when using Gradle.

Instead of using the default web interface, there is even a more convenient way of generating your project directly in IntelliJ IDEA.

File → New Project → Spring Initializr

Yeoman

Yeoman is an interesting tool, which allows you to generate a project using one of their many generators.

What's interesting is that unlike Maven, it is not focused solely on the JVM ecosystem. You can generate a project for pretty much any language or framework and their combinations.

That means you can have a generator for an application with Java backend, React frontend and Docker integration. Or anything else you can think of as there are many generators available.

JHipster

JHipster is actually a Yeoman generator under a hood. It allows you to generate Spring Boot projects with Frontend in Either React, Angular or Vue.

There is much more, though. It optionally supports microservices and cloud deployment. It integrates sass, webpack, bootstrap, various databases, ELK, caching, Docker, WebSockets, and much more.

It is definitely worth checking if you want to easily generate your whole application front to back with a standardized opinionated stack.

Conclusion

Maven archetypes offer you an easy way to generate basic project scaffolding for various project types without the hassle of a manual approach. Still, there are some alternatives mentioned above which may be better in some cases such as Spring Boot Initializr or JHipster.