vaadin-connect

vaadin-connect copied to clipboard

= 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.

[source,java] .DateService.java

@VaadinService public class DateService { public int getDayOfYear(LocalDate date) { return date.getDayOfYear(); } }

[source,typescript] .app.ts

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:

• Automatic JSON serialization and parsing. Vaadin Connect supports builtin Java data types and Beans.
• Automatic validation based on Java annotations is provided on both the client and the server.
• Backend errors and exceptions are passed to the frontend to inform the UI.

=== 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:

• Easy to access the API. No manual REST network requests to API endpoints needed, instead there are generated async TypeScript methods to call.
• IDEs provide auto completion and code suggestions for the generated TypeScript services.
• Using TypeScript provides type checking for the frontend code.

=== Security

The authentication layer based on OAuth 2.0 is included in Vaadin Connect.

• The backend requires authentication for all annotated service methods by default.
• A configurable OAuth 2.0 authentication server is included in the backend and supported on the frontend.
• The frontend client authenticates either: by providing a user and password pair, or by using a 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:

• Uses npm for frontend package management.
• Includes the @webcomponents/webcomponentsjs polyfill.
• Provides ES modules support with bundling (more on that below).

=== 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:

• The modern .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.
• The legacy .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

• <<doc/getting-started#,Check the short Getting Started Tutorial>>
• https://github.com/vaadin/base-starter-connect[Try out a Starter project]