= This project has been archived
Vaadin Connect is being integrated into link:https://github.com/vaadin/flow[Vaadin Flow]. Please file any issues or improvement suggestions in that repository.
= Vaadin Connect
== What is Vaadin Connect
Vaadin Connect is a bridge between Java backend services and a TypeScript frontend. It includes an HTTP API server and generates TypeScript clients to call the Java backend in a type-checkable way. Security is built-in by default.
The following two snippets show the basic code that you need to write in order to expose a Java service and consume it from TypeScript.
import * as dateService from './generated/DateService';
showDayOfYearButton.onclick = async() => { const dayOfYear: number = await dateService.getDayOfYear(new Date()); dayOfYearLabel.textContent = dayOfYear; };
This graph outlines in a simple way the elements involved when using a service:
.Simplified Vaadin Connect RPC sequence diagram image::doc/simplified-rpc-sequence.svg[opts=inline]
=== Elements of Vaadin Connect
The Vaadin Connect collection of tools and libraries includes:
vaadin-connect
Java library providing backend services based on the Servlet
API v3.@vaadin/connect
TypeScript (ES module) client library consuming Vaadin
Connect services.vaadin-connect-maven-plugin
Maven plugin generating TypeScript API modules
from Java service classes.vaadin-frontend-server
An optional java package that helps to create a Single-page application (SPA).https://github.com/vaadin/base-starter-connect[base-starter-connect]
The example application project.[NOTE]
The current version of the vaadin-connect
Java library is implemented using link:https://spring.io/projects/spring-framework[Spring].
== Why to use Vaadin Connect?
Vaadin Connect gives a "better than REST" experience for the development teams that use Java on the backend, and TypeScript on the frontend.
=== Easy to expose business services
Vaadin Connect is designed to facilitate the access of business procedures that run in the java backend, hence, business logic can still be developed in Java taking advantage of its security and type-safety.
Vaadin Connect provides the the following features:
=== Type-checkable API access from TypeScript
Vaadin Connect generator produces TypeScript frontend counterparts from the annotated Java service classes. The key benefits of this approach are:
=== Security
The authentication layer based on OAuth 2.0 is included in Vaadin Connect.
refresh_token
from a previous successful authentication.=== Easy to scale
In Vaadin Connect, the backend services are stateless. Instead of storing the
sessions on the backend server, every authenticated request comes with an
access_token
containing the information about the user.
This enables easy cluster backend deployments, as there is no need to manage a shared session storage between multiple backend servers.
NOTE: Although Vaadin Connect services do not need session to work, the app logic still can use sessions when needed.
=== Works with any UI framework
Vaadin Connect is agnostic to frontend frameworks, and can be used with React, Angular, Vue, etc.
=== Supports Vaadin components
The link:https://github.com/vaadin/base-starter-connect[`base-starter-connect`] example application provides the basic structure of a new application made with Vaadin Connect.
The frontend part of the base-starter-connect
uses Vaadin components, as well
as provides support for third-party and community Web Components out-of-the-box:
npm
for frontend package management.@webcomponents/webcomponentsjs
polyfill.=== Modern ES6 / ES2017 based frontend
Vaadin Connect generated TypeScript is compiled to ES modules output format. ES modules is an established web standard, that allows static code analysis and processing, and is supported by all modern web browsers, as well as many existing tools and libraries.
The generated services are build around async
/ await
, and use the fetch
API
as a network layer.
The base-starter-connect
example application provides bundling, transpilation,
and necessary polyfills for the frontend code. The bundling is made with
differencial serving in mind, and results in two bundle versions:
.js
bundle, targeted for browsers having native ES6, fetch
and
modules support. This allows to decrease the bundle size for modern web
browsers by excluding unnecessary polyfills and using a more concise syntax..es5.js
bundle with all the classes transpiled to ES5, and all
the polyfills included. This enables browser support down to IE 11.=== Next Steps