Creating New Projects

The spring boot new command makes it easy to create Spring Boot applications.

This command copies the content from the source code repository of an existing fully functional Spring Boot application to create a new project.

To get started, specify the --name option, which creates a basic RESTful web application with a test. You can also use the --from option to create projects with different functionalities, such as Spring Data JPA or Spring Cloud Stream.

For further customization, you have the flexibility to specify various options (such as --group, --artifact-id, and --version) as well as --package-name and --description. If you provide the --package-name, the code is refactored after cloning the source code repository.

The following sections provide detailed explanations of each of these topics.

For more information on adding additional code to an already existing application, see spring boot add and User Defined Commands.

Quick Start

To quickly create a simple web application in a new directory, run the following commands:

spring boot new my-app
cd my-app
./mnvw spring-boot:run

This creates a basic web application in the my-app directory. The --name option is passed positionally in this example, equivalent to spring boot new --name my-app.

If you prefer to create a project in your current working directory, specify . as the name:

mkdir my-new-app
cd my-new-app
spring boot new .
./mvnw spring-boot:run

To create applications with different functionality, use the option --from in the spring boot new my-app command. Since --from comes after --name you can use positional parameters.

For example:

spring boot new my-app jpa
cd my-app
./mnvw spring-boot:run

The preceding command creates a new application that includes Spring Data JPA functionality.

In the preceding example, both the name of the new app (my-app) and the --from option (jpa) are provided as positional parameters. It is equivalent to using spring boot new --name my-app --from jpa.

The name, jpa, is registered with the default getting started project catalog and serves as an alias to a specific URL with some additional metadata. This is described more in the following section.

Creating by Name

The project catalog contains a list of code repositories that demonstrate specific Spring technologies. The repositories in the default project catalog, resembling the content in the Spring Getting Started Guides, provide a range of functionalities.

You can have the option to register your own catalogs, offering code repositories of varying complexity and functionality.

The project catalog helps you find the desired functionality for your new projects. You can also refer to the project names from the project catalog when adding code to an existing project by using the spring boot add command.

To view the registered projects in the default "getting started" catalog, run the following command:

spring project-catalog list

This command displays the available project catalogs that you can use with the spring boot new command:

┌────┬──────────────────────────────────────────────┬───────────────────────┬───────────────────┐
│Name│URL                                           │Description            │Tags               │
├────┼──────────────────────────────────────────────┼───────────────────────┼───────────────────┤
│gs  │https://github.com/rd-1-2022/spring-gs-catalog│Getting Started Catalog│[java-11, boot-2.7]│
└────┴──────────────────────────────────────────────┴───────────────────────┴───────────────────┘
```

To view the available projects, use the following command:

spring project list

This command provides a list of projects that you can use. Each project has a name that you can passed to spring boot new. The following table shows typical output:

┌─────────────┬────────────────────────────────────────────────────────┬─────────────────────┬───────┬───────────────┐
│Name         │URL                                                     │Description          │Catalog│Tags           │
├─────────────┼────────────────────────────────────────────────────────┼─────────────────────┼───────┼───────────────┤
│web          │https://github.com/rd-1-2022/rest-service               │Hello, World RESTful │gs     │[rest, web]    │
│             │                                                        │web service.         │       │               │
├─────────────┼────────────────────────────────────────────────────────┼─────────────────────┼───────┼───────────────┤
│jpa          │https://github.com/rd-1-2022/rpt-spring-data-jpa        │Learn how to work    │gs     │[jpa, h2]      │
│             │                                                        │with JPA data        │       │               │
│             │                                                        │persistence using    │       │               │
│             │                                                        │Spring Data JPA.     │       │               │
├─────────────┼────────────────────────────────────────────────────────┼─────────────────────┼───────┼───────────────┤
│scheduling   │https://github.com/rd-1-2022/rpt-spring-scheduling-tasks│How to schedule tasks│gs     │[scheduling]   │
├─────────────┼────────────────────────────────────────────────────────┼─────────────────────┼───────┼───────────────┤
│config-client│https://github.com/rd-1-2022/rpt-config-client          │Using the Config     │gs     │[config]       │
│             │                                                        │Client library       │       │               │
├─────────────┼────────────────────────────────────────────────────────┼─────────────────────┼───────┼───────────────┤
│eureka       │https://github.com/rd-1-2022/eureka                     │Spring Cloud Eureka  │gs     │[cloud, eureka]│
│             │                                                        │Server               │       │               │
├─────────────┼────────────────────────────────────────────────────────┼─────────────────────┼───────┼───────────────┤
│graphql      │https://github.com/rd-1-2022/rpt-spring-graphql         │Spring GraphQL       │gs     │[graphql]      │
└─────────────┴────────────────────────────────────────────────────────┴─────────────────────┴───────┴───────────────┘

To create a new project that uses Spring Data JPA, run the following command:

spring boot new my-jpa jpa

This command uses the application from the source code repository URL: github.com/rd-1-2022/rpt-spring-data-jpa.

You can also use the name of the project as the argument to the spring boot add command.

Creating by URL

Instead of adding a project to the Spring CLI so as to reference it with a short name, you can use the URL of the project’s source repository directly.

For example, to create the Spring JPA project, you can use the following command:

spring boot new my-jpa https://github.com/rd-1-2022/rpt-spring-data-jpa

Options

The spring boot new command takes the following options, which you can see by running the following command:

spring boot new --help

That command shows the following output:

NAME
       boot new - Create a new Spring Boot project from an existing project

SYNOPSIS
       boot new --from String --name String --group-id String --artifact-id String --version String --description String --package-name String --path String --help

OPTIONS
       --name String
       Name of the new project
       [Mandatory]

       --from String
       Create project from existing project name or URL
       [Optional]

       --group-id String
       Group ID of the new project
       [Optional]

       --artifact-id String
       Artifact ID of the new project
       [Optional]

       --version String
       Version of the new project
       [Optional]

       --description String
       Description of the new project
       [Optional]

       --package-name String
       Package name for the new project
       [Optional]

       --path String
       Path to run the command in, most of the time this is not necessary to specify and the default value is the current working directory.
       [Optional]

       --help or -h
       help for boot new
       [Optional]

Options and Default Values

By specifying just the --name option, the artifactId defaults to the value of the --name option. Consider the following example:

spring boot new --name myapp
Cloning project from https://github.com/rd-1-2022/rest-service
Created project in directory 'myapp'

In the generated pom.xml, the name (myapp) is used as the artifactId and the name of the project:

	<groupId>com.example</groupId>
	<artifactId>myapp</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>myapp</name>
	<description>RESTful web application</description>

Adding the --groupid option changes not only the value of the groupId tag but also the package name. A refactoring of the project to the new package name is performed. Consider the following example:

$ spring boot new --name myapp --group-id com.xkcd
Cloning project from https://github.com/rd-1-2022/rest-service
Refactoring package to com.xkcd.myapp
Created project in directory 'myapp'

The generated pom.xml contains the following content:

	<groupId>com.xkcd</groupId>
	<artifactId>myapp</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>myapp</name>
	<description>RESTful web application</description>

The directory structure of the project is as follows:

$ tree myapp/
myapp/
├── LICENSE
├── mvnw
├── mvnw.cmd
├── pom.xml
├── README.adoc
└── src
    ├── main
    │   └── java
    │       └── com
    │           └── xkcd
    │               └── myapp
    │                   ├── Application.java
    │                   └── greeting
    │                       ├── GreetingController.java
    │                       └── Greeting.java
    └── test
        └── java
            └── com
                └── xkcd
                    └── myapp
                        └── greeting
                            └── GreetingControllerTests.java