How to Create a Custom Maven Archetype

Maven archetype is a powerful project template tool, which used to create various kinds of maven powered project in the much easier and faster way. Sometime, we prefer to create our own templates to help the our specific works with maven. It is not hard but the good guide could be tricky to locate online. So I make this quick start guide to help the impatient people.

Simple Process

The easy method I found is as follows:

1. create/locate a sample java maven project, which is what your archetype will generate later. Let us call the chosen sample project as target project
2. create archetype from target project. Under target project, type-in the following command:

mvn archetype:create-from-project


3. the resulted archetype, let us call it custom archetype, is generated under the directory of current project:

target/generated-sources/archetype/


4. improve custom archetype in the following ways:
1. configure target/generated-sources/archetype/pom.xml to update the information about this archetype project, such group id, artifact id, version and etc. I suggest to add following code snippet into it to avoid the UTF encoding warning during the process of archetype generate:

  <properties>
    <project.build.sourceencoding>UTF-8</project.build.sourceencoding>
  </properties>

2. configure target/generated-sources/archetype/src/main/resources/META-INF/maven/archetype-metadata.xml to setup which directories & files should be generated, and default properties if needed, see more details
3. modify the source file templates of target project if you like. These template files may contain the property placeholders powered by Velocity. You can locate them under the following directory:

target/generated-sources/archetype/src/main/resources/archetype-resources/


4. you may move the directory archetype out of target project. The directory archetype contains all files needed for custom archetype, It is an independent maven project from target project

target/generated-sources/archetype/


5. install custom archetype into your local maven repository so that you can try it. Under custom archetype directory, type-in the following command:

mvn clean install


6. test custom archetype by generating the target project from scratch. Let's assume the artifact id of your custom archetype is my-custom-archetype. Switch to another arbitrary working directory, type-in the following command:

mvn archetype:generate -Dfilter=my-custom-archetype


7. follow the instructions provided by maven, your target project should be generated under the current working directory when it complete successfully. You could start to test the resulted target project. You may repeat the step 4 to step 7 until you are satisfied with the custom archetype
8. Well done, your custom archetype is ready to work. You may choose to release it to your organization's maven repository, or open source and release to public maven repository, or simply keep using it as a secret weapon in your own machine. It is up to you. Please enjoy the efficiency boost for future development works!

Last Word

There is a alternative way to create custom archetype. You may create a sample archetype directly by using a maven built-in archetype called maven-archetype-archetype, and then progressively modify it to archive what you want. This may be a better choice under certain cases. To do this way, choose a arbitrary working directory, and type-in the following command:

mvn archetype:generate
  -DarchetypeArtifactId=maven-archetype-archetype 
  -DgroupId=[group id of your custom archetype]
  -DartifactId=[artifact id of your custom archetype]

Stack & Version

• JDK - 1.8
• Apache maven - 3.5.4
• Apache maven archetype plugin - 3.0.1

Reference

• Apache maven
• Creating an archetype from an existing project
• Youtube video - How To Create a Custom Maven Archetype (2017), 13.5 minutes
• Maven Archetype Plugin - archetype:create-from-project