Quarkus Quinoa - Getting Started

Quinoa is a Quarkus extension which eases the development, the build and serving single page apps or web components (built with npm : React, Angular, Vue, Lit, Svelte, Astro, SolidJS …) alongside other Quarkus services (REST, GraphQL, Security, Events, …).

Live code the backend and frontend together with close to no configuration. When enabled in development mode, Quinoa will start the UI live coding server provided by the target framework and forward relevant requests to it. In production mode, Quinoa will run the build and process the generated files to serve them at runtime.

Prerequisite

Create or use an existing Quarkus application
Add the Quinoa extension
Install NodeJS (https://nodejs.org/) or make sure Quinoa is configured to install it, see the following example.

quarkus.quinoa.package-manager-install.node-version=20.10.0
quarkus.quinoa.package-manager-install.npm-version=10.2.3

Installation

Create a new Quinoa project (with a base Quinoa starter code):

With code.quarkus.io
With the Quarkus CLI:

quarkus create app quinoa-app -x=io.quarkiverse.quinoa:quarkus-quinoa

Then start the live-coding:

quarkus dev

And navigate to http://0.0.0.0:8080/quinoa.html

You could also just add the extension (but you won’t get the starter code):

With the Quarkus CLI:

quarkus ext add io.quarkiverse.quinoa:quarkus-quinoa

In your pom.xml file, add this dependency:

<dependency>
    <groupId>io.quarkiverse.quinoa</groupId>
    <artifactId>quarkus-quinoa</artifactId>
    <version>2.5.0</version>
</dependency>

Getting Started

If not yet created by the tooling, you will need a Web UI directory in src/main/webui. This directory will contain your npm Web application code with a package.json.

The location is configurable, the directory could be outside the Quarkus project as long as the files are available at build time.

You may use an existing Web UI or generate a starter application from any existing npm based Web Framework. Some Web Frameworks are detected and preconfigured with sensible defaults. If your Web Framework is not part of the detected frameworks or if you changed the configuration, you can always configure Quinoa to work with it.

The key points for Quinoa are:

the package.json scripts: build, optionally start/dev and test
the directory where the web files (index.html, scripts, …) are generated: dist, build, …
the port used by the dev-server

application.properties

quarkus.quinoa.dev-server.port=3000
quarkus.quinoa.build-dir=dist

Start the Quarkus live coding:

$ quarkus dev

Build your app:

$ quarkus build
$ java -jar target/quarkus-app/quarkus-run.jar

It’s done! The web application is now built alongside Quarkus, dev-mode is available, and the generated files will be automatically copied to the right place and be served by Quinoa if you hit http://localhost:8080

With Quinoa, you don’t need to manually copy the files to META-INF/resources. Quinoa has its own system and will provide another Vert.x route for it. If you have conflicting files with META-INF/resources, Quinoa will have priority over them.