vaadin-framework/documentation/migration/migrating-to-vaadin8.asciidoc

---
title: Migrating to Framework 8
order: 1
layout: page
---
// TODO: Fix release note links to point to 8.0.0
[[migration]]
== Migration from Framework 7 to Framework 8

Most Vaadin Framework 7 applications will need some changes when migrating to Vaadin Framework 8.
To make migration from version 7 to 8 as straightforward as possible, Vaadin Framework 8 ships with compatibility packages that include all the old features and APIs that have changed between versions.

The recommended migration path to take for any non-trivial Vaadin application is to first switch any incompatible components to using the APIs available in the compatibility packages, after which parts of the application can be migrated separately.
This is primarily to get an existing Framework 7 project up and running with Framework 8 as quickly as possible, as well as to avoid having to switch to using completely new APIs throughout an entire project all at once.

=== Updating Project Dependencies

The very first step in migration is to ensure that your project is configured to use Framework 8 dependencies, as well as include any of the desired compatibility packages needed in your migration.
Also note that Framework 8 requires JDK 8 for development.
For deployment configurations, refer to the list of supported technologies in the release notes, available at link:https://vaadin.com/download/prerelease/8.0/8.0.0/8.0.0.beta1/release-notes.html#supportedversions[].

==== Updating Maven Dependencies

For maven based projects including compatibility packages is simply a matter of changing the artifactId of the desired non-compatibility dependency to the compatibility variant.
For example in the case of changing the vaadin-server dependency from Framework version 7.7.6 to 8.0.0 would require changing

```xml
<dependency>
  <groupId>com.vaadin</groupId>
  <artifactId>vaadin-server</artifactId>
  <version>7.7.6</version>
</dependency>
```

to either

```xml
<dependency>
  <groupId>com.vaadin</groupId>
  <artifactId>vaadin-compatibility-server</artifactId>
  <version>8.0.0</version>
</dependency>
```

for including both compatibility features as well as non-compatibility ones, or alternatively

```xml
<dependency>
  <groupId>com.vaadin</groupId>
  <artifactId>vaadin-server</artifactId>
  <version>8.0.0</version>
</dependency>
```

to only include Framework 8 features.
The full list of compatibility packages available for Framework 8 are the following:

* vaadin-compatibility-server
* vaadin-compatibility-client
* vaadin-compatibility-client-compiled
* vaadin-compatibility-shared
* vaadin-compatibility-themes

IMPORTANT: The themes Reindeer, Runo, Chameleon and Base have been deprecated in Vaadin Framework 8 and they now reside in the compatibility-themes package.
Applications still using any of these themes must include this package.

==== Add-ons

As with projects themselves, some addons built for Framework 7 will not be directly compatible with Framework 8, thus any add-on dependencies must also be updated to versions that are compatible with Framework 8.
Be sure to check the add-on directory at link:https://vaadin.com/directory[] for updates to add-ons your project depends on.

For add-on developers, the same steps outlined in this guide can also be applied to upgrading your add-ons from Framework 7 to 8.

=== Using The Compatibility Packages

Once your project's dependencies have been updated for Framework 8 migration there are a few steps to begin using the compatibility versions of the old APIs, namely changing of imports and ensuring that your widgetset is correctly set up.
Optionally, if you are using Vaadin Designer or declarative files otherwise, the tag names for compatibility components need to be updated.

==== Changing Imports

The only change to classes in the compatibility packages is the change in their classpath. All compatibility classes can be found under `com.vaadin.v7.*`.
For example the compatibility `TextField` is available through the import `import com.vaadin.v7.ui.TextField`, given that the project dependencies have been set up to include the compatibility variants, as described in the previous section.

==== Widgetset Changes

When using compatibility packages in your project you need to changes references from the default vaadin client side widgetset `com.vaadin.DefaultWidgetSet` to the one containing the compatibility packages `com.vaadin.v7.Vaadin7WidgetSet`, which is available in the vaadin-compatibility-client-compiled maven dependency.
Typically, widgetset recompilation will handle this automatically for you, except for the following two cases which should be handled manually:

* Your project defines a custom widgetset, in which case you need to make sure `Vaadin7WidgetSet` is inherited
* An UI in your project defines its widgetset with the annotation `@WidgetSet("com.vaadin.DefaultWidgetSet")`, which should be changed to `@WidgetSet("com.vaadin.v7.Vaadin7WidgetSet")`

==== Using Compatibility Components In Declarative Files

Using components from the compatibility packages in your declarative files only requires you to change the prefix from `vaadin-` or alternatively `v-` to `vaadin7-`.
For example, the conversion of a `com.vaadin.ui.TextField`

```html
  <vaadin-text-field _id="textField" />
```

to its compatibility equivalent, `com.vaadin.v7.ui.TextField`, would simply be achieved with the following replacement

```html
  <vaadin7-text-field _id="textField" />
```

in the corresponding design html file.

==== The Migration Tool

To ease the process of the initial changing of imports and prefixes in design files, a tool for automatically applying these changes to a project is available at link:https://github.com/vaadin/framework8-migration-tool[].
Please refer to the README available in the repository for up to date instructions on how to run the tool on your project.

=== Next Steps

By replacing incompatible components of your application with ones from the compatibility packages your project should now be in a state where it can be compiled and run.
To get started with using the new Framework 8 features it is now only a matter of replacing the usage of compatibility APIs where desired.

Aside from minor API and default changes at the component level, the largest change in Vaadin Framework 8 is its new data model.
Framework 8 no longer uses `Item`, `Property` nor `Container`.
These building blocks for the old data binding have been deprecated in favor of more Java 8 friendly APIs.

The new data model can be roughly split into three main topics, namely binding data to field components, providing data to listing components and handling selections.
The revised <<dummy/../../../framework/datamodel/datamodel-fields.asciidoc, "Binding Components to Data">> chapter is the recommended resource to get started with learning these new concepts.
For migration from Framework 7 the key references are the following sections:

* <<dummy/../../../framework/datamodel/datamodel-fields.asciidoc, "Editing Values in Fields">> and <<dummy/../../../framework/datamodel/datamodel-forms.asciidoc, "Binding Data to Forms">>, which cover the new data binding concepts that replace `Property` and `FieldGroup`.

* <<dummy/../../../framework/datamodel/datamodel-providers.asciidoc, "Showing Many Items in a Listing">>, which covers the new `Container` and `Item` replacement, the `DataProvider`, as well as the associated sorting and filtering APIs.

* And for the new selection APIs,  <<dummy/../../../framework/datamodel/datamodel-selection.asciidoc, "Selecting Items">>.

For a full list of incompatible changes between Framework 7 and 8, please refer to the _Incompatible or Behavior-altering Changes_ section of the release notes, available at link:https://vaadin.com/download/prerelease/8.0/8.0.0/8.0.0.beta1/release-notes.html#incompatible[].