The instructions in this article are applicable only if you want to tinker with the LuciadRIA sample code yourself.

To start the LuciadRIA samples as they come in the release, without modification, start the sample server with the startSampleServer script, and go to Samples to select and launch samples.

Quick overview

  1. Make sure your system setup covers all prerequisites, as described in the Hardware and software requirements.

  2. Extract the LuciadRIA release correctly, following the installation instructions.

  3. Run npm install in the root of the LuciadRIA distribution.
    This command installs all sample dependencies. You must install these once for a release. See Installing dependencies.

  4. Start the sample server with the startSampleServer script in the root of the LuciadRIA distribution. See Running the sample server for more information.

  5. Run npm run dev in the directory of the sample you want to edit and run.
    A browser window opens automatically. It runs your sample and watches the files in that directory. If you edit and save a file in that directory, the running sample changes automatically, and the browser window refreshes. See Running a Vite dev server for a sample.

Installing dependencies

Before you can deploy the samples in the samples/ directory, you must install all dependencies of the LuciadRIA distribution and its individual samples. To install the dependencies, you must execute npm install in the root of the LuciadRIA distribution. This command installs all development dependencies declared in the root package.json and the ones declared in the package.json of the workspaces that are defined. The NPM workspaces also take care of dependency hoisting: dependencies that are common to different samples are only installed once in a higher-level node_modules directory.

After installing the dependencies of all samples, you can set up your web application.

Running the sample server

Several samples don’t fetch their data locally, but request it from a server, or use other data services. The LuciadRIA distribution offers a sample server to host those services. You can run the sample server by executing the startSampleServer script. http://localhost:8072 hosts the server by default.

Running a Vite dev server for a sample

When you’re developing an application, it’s useful to run a development server, or dev-server. A development server serves the application and watches the source files for changes. It serves those changes without a server restart. To start a Vite dev server for a sample application in the LuciadRIA distribution:

  1. Make sure that you have bootstrapped the sample dependencies, as explained in Installing dependencies.

  2. Go to one of the sample folders within the samples/ directory and execute npm run dev.
    By default, a dev server starts hosting the chosen sample on http://localhost:3001/. It also watches the source files so that it can pick up and serve any changes in the source code or styling as long as it’s running.

You can also add arguments to npm run dev by adding -- and one or more argument tags at the end. Vite’s CLI supports, among others:

--port <PORT>

Specify the port on which the Vite dev server must run.

For example, if you want to run on port 3002, you run the following command:

npm run dev -- --port=3002

Make sure to insert the double dashes -- before the argument. They tell npm to pass the next arguments down to the Vite CLI.

For more information about the available CLI flags, see the Vite CLI documentation.

Other sample-specific behavior, such as running with a 3D RIAMap (is3D) or the sample server URL (sampleServerUrl), is configured through the sample’s own vite.config.ts file, which passes these as options to the createSampleViteConfig factory shared by all samples: 

import createSampleViteConfig from "@luciad/ria-toolbox-config/vite.config.ts";
export default createSampleViteConfig(import.meta.url, {is3D: true});

To run the dev server over HTTPS with a generated self-signed certificate, set the RIA_VITE_HTTPS environment variable before running npm run dev: 

# On Mac and Linux:
RIA_VITE_HTTPS=1 npm run dev

# On Windows (cmd.exe):
set RIA_VITE_HTTPS=1&&npm run dev

The Vite configuration of all samples extends the shared factory in toolbox/ria/config/vite.config.ts. See the Vite configuration reference web page for more information.

Building and running the sample

Building and running samples may require a significant amount of memory. To execute the build, you need to configure the amount of memory that Node.js can use. You can do so by setting the NODE_OPTIONS environment variable to --max-old-space-size=4096.

To build and run the application, take these steps:

  1. Run the npm run build command in the sample directory.
    The sample is packaged to packed-samples/ria/<sample>.

    The original sample in that directory will be overwritten, so it might be a good idea to back that up first.

  2. Start the sample server by running the startSampleServer script.

  3. Open your browser, and point it to http://localhost:8072/samples/<sample>. A new web page displays your application.

This uses the same Vite configuration as discussed in Running a Vite dev server for a sample.

When you’re deploying a real application, just running the provided Vite dev server isn’t enough. You must take care of other steps, such as minification/uglification or chunk splitting as well, before you can serve the application.

Transpiling TypeScript samples to JavaScript

Some samples contain TypeScript code. To re-use sample code in a JavaScript project, you can automatically convert the TypeScript code to JavaScript. You can do this by running npm run transpile-to-js in the sample directory. This command generates a ./transpiled directory inside the sample. This folder contains a full copy of the sample source code, but with TypeScript transpiled down to JavaScript. Optionally, you can also generate TypeScript declaration files (.d.ts files) in the transpiled directory by running npm run transpile-declarations in the sample directory. Even when you’re not using TypeScript, these files give code completion hints to your IDE about the corresponding JavaScript files.

Use of React in LuciadRIA samples

The UI components in the LuciadRIA samples have been implemented with React. We use React in our sample code because it’s a very popular UI library.

Note that you don’t have to use React with LuciadRIA. You’re free to use any UI library you want. Even if you’re using a different UI library, such as Angular or Vue, you can still use the sample code as inspiration for your own UI components.

Finding React components in the sample structure

You can find the React UI components in the components directory of a sample. To find components that are re-used across samples, see the samples/common directory, also known as the @luciad/ria-sample-common NPM package.

Sample code highlights

toolbox

This folder contains the source code of the LuciadRIA Toolbox components. See Use the LuciadRIA Toolbox for more information.

toolbox/ria/config

This folder contains configuration shared across LuciadRIA samples, like TypeScript or Vite configuration files.

samples/common/ui

This folder contains React UI elements that are used across LuciadRIA samples.

samples/common/ui/map/SampleMap

A container for a LuciadRIA RIAMap. It renders a <div/> element and creates a RIAMap instance with that element.

samples/common/ui/map/SingleMapSample

A sample based on a single map that covers the entire window. It has a SampleMap, overlay components, and a placeholder for UI below the map, such as the bottomBar property. Most LuciadRIA samples are based on this component.

samples/common/ui/map/DualMapSample

A sample based on 2 maps that cover the entire window. It has 2 SampleMap components, each with its own overlay components.

samples/common/ui/overlay

This folder contains a bunch of overlay components, such as a layer tree UI, a mouse location components, a scale indicator, and navigation controls.

samples/common/ui/sample-common-style.css

This file contains CSS variables and common styles that all LuciadRIA samples use.

See Reuse sample code in your own application for more information about our sample code.