Hilla Documentation

TypeScript Client Library

Hilla consists of two parts: a backend and a client. The client part is represented by the @hilla/frontend library, which is able to support the features the backend part provides.

One of the main public entities of the library is the ConnectClient object, which provides a seamless way to communicate with Hilla endpoints on the backend.

Default TypeScript Client

The default TypeScript client is the module that gets generated by the Hilla Maven plugin for a particular project.

The module contains the ConnectClient implementation, which is set up to communicate with the backend of the project.

Generated Client Modules

Along with the default TypeScript client, the Hilla Maven plugin is capable of generating specific modules for each Hilla endpoint defined in the backend part. These modules also use the default TypeScript client described above to communicate with the backend.

Usage Example

Consider a Hilla backend that’s started on the /customEndpoint endpoint and has a single endpoint with the name SingleEndpoint and a method customMethod() that takes a parameter number.

To access this method from the client part, depending on how many generated files are present, you can use one of the following approaches. The required @hilla/frontend TypeScript library is automatically installed by the Hilla Maven plugin.

Using the Generated Client Module

The endpoint method can be called via the generated module method:

import { SingleEndpoint } from 'Frontend/generated/SingleEndpoint';

(async() => {
  await SingleEndpoint.customMethod(4);
})();

Using the Generated Default Client

As an alternative to the generated module, the default TypeScript client API can be used to access the Hilla endpoint as follows:

import client from 'Frontend/generated/connect-client.default';

(async() => {
  await client.call('SingleEndpoint', 'customMethod', {number: 4});
});

Using the Hilla TypeScript Client Library

Using the client library requires an extra step where we specify the endpoint of the server to send the requests to:

import { ConnectClient } from '@hilla/frontend';
const client = new ConnectClient({endpoint: '/customEndpoint'});

(async() => {
  await client.call('SingleEndpoint', 'customMethod', {number: 4});
});