This repository holds the application that you build in the Vaadin tutorial: the product catalog of the back office of a fictional Click & Collect service. Users can list, sort, filter, view, edit, add, and delete products, and share links to individual products. The catalog runs inside a main layout with a navigation menu, next to a placeholder view for orders.
The main branch holds the finished application, as it is at the end of the last step of the tutorial. You can run it and read its code before you follow the tutorial. Every step also has a branch of its own, so that you can start the tutorial from any step, or compare your code with the code at the end of a step.
You need a Java Development Kit (JDK), version 21 or newer. Start the application with:
./mvnwOn Windows, run mvnw instead. The application opens at http://localhost:8080. Its database lives in memory, so your changes disappear when you restart the application, and the sample data comes back.
To build the application for production and run its tests, run:
./mvnw verifyThe application is a Spring Boot application, with an in-memory H2 database and Spring Data JDBC.
com.example.productholds the product catalog: the view, its form and dialog, the application service, and the repositories. The classes are package-private, since nothing outside the package uses them.com.example.base.uiholds the main layout and the title bar that the views share.com.example.orderholds the placeholder view for orders.src/test/java/com/example/productholds a test of the service, and browserless tests of the view. The browserless application context that the view tests use is configured inBrowserlessContextConfiguration.schema.sqlanddata.sqlcreate the database and its sample data when the application starts.
Each of these branches holds the application as it is at the end of a step of the tutorial:
To start the tutorial at a step, clone the branch of the step before it. For example, to start at Edit Details, run:
git clone --branch step/show-details https://github.com/vaadin/tutorial.gitEach step is one commit on top of the previous step, so the history of step/add-tests lists the steps of the tutorial, and each commit shows what its step changes. In a clone, git show origin/step/edit-details shows the changes of the Edit Details step.
Nobody edits the step branches by hand. GenerateSteps.java generates them from the tutorial in vaadin/docs. It downloads the project skeleton that the Set Up Project step links to, adds the dependencies and SQL files that the step lists, and then applies the listings in the "Complete Code for This Step" section of each step, one step at a time.
The CI workflow runs on every push to main, on every pull request, and every Monday. It:
- builds
mainand runs its tests, - generates the steps from the branch of vaadin/docs in
DOCS_REF, and builds and tests each of them with./mvnw verify, - checks that
mainmatches the last step, except for this README and the.githubdirectory, and that this README lists every step branch, - on
main, commits each step that changed on top of the previous step, and force-pushes its branch, and the branches of the steps after it, and - on
main, opens a pull request from theupdate-mainbranch that updatesmainto the last step, if they don't match.
To fix the code, fix the tutorial in vaadin/docs. The next CI run on main updates the step branches. If the last step changed, it also opens a pull request that updates main, or updates the pull request that is already open. Review and merge it. Until then, the check of main fails.
The pull request replaces every file except README.md and the .github directory, and removes the files that the last step doesn't have. If a step was added to the tutorial, or removed from it, update the table of step branches in this README in the same pull request. Its check fails until you do. GitHub doesn't run workflows for pull requests that a workflow opens, so CI runs on the update-main branch through a manual workflow run, whose checks appear on the pull request. If main matches the last step again, for example because someone updated it by hand, CI closes the pull request.
To generate the steps yourself, for example to see what a change to the tutorial does, use the branch of vaadin/docs in DOCS_REF, here v25.3:
git clone --depth 1 --branch v25.3 --filter=blob:none --sparse https://github.com/vaadin/docs.git ../docs
git -C ../docs sparse-checkout set --no-cone /articles/_vaadin-version.adoc /articles/getting-started/tutorial/ /src/main/resources/META-INF/resources/vaadin/tutorial/
java .github/steps/GenerateSteps.java ../docs ../stepsThen .github/steps/update-main.sh ../steps shows how main differs from the last step, and .github/steps/commit-steps.sh ../steps shows which step branches would change. Neither pushes anything unless you add --push.
When a new Vaadin version becomes the one at https://vaadin.com/docs/latest, set DOCS_REF in the CI workflow to the branch of vaadin/docs for that version, such as v25.4. The next CI run on main then opens a pull request that updates main to it.