Skip to main content
Version: 2.2.0

Pre-requisites

The following section assumes you have installed all the tools required for web development from our tools section.

Before you move on, it is also mandatory that you read through the key technology list in our web technologies section and you understand the justification for each one, especially if you're not familiar with the specific technology.

info

It is presumed that you already have a Web Base prepared and ready for you install modlets, otherwise, please go to the Web Framework quickstart section to initialize your Web Base.

It is also presumed that you are already familiar with running a local development environment, otherwise, please go to the Local Dev Environment to prepare your machine for local development.

Installation​

1. CLI tool installation of GIS Modlet​

Navigate to the web folder in your Web Base and run the following command:

web-base/web
npx cli install gis
info

If "cli" is an unknown command, you might have to run npx cli instead of cli or, run npm install first, because the CLI tool might not already be in your global or local node_modules folder.

You'll then be prompted to choose your 'root folder', use the default (current working directory).

Follow the CLI tool's instructions. the modlet will be installed, with the appropriate files being copied over, and dependencies will be added and copied into your package.json.

1.1 Move the new environment variables to your template​

The CLI tool appends new environment variables used by the modlet into your .env.template file, if you've already set up your .env file, you should manually copy these values over. Otherwise, you can use the entire defaults by copying the template file and renaming it to .env.

web-base/web
cp .env.template .env

2. Manual installation of GIS Modlet​

The GIS has extra steps that are already automatically executed by the CLI tool. If you've chosen no during the setup stage of the CLI tool, or wish to know what the tool actually did, you can refer to the following:

2.1 Add the following properties to your .env file​

These default values will work if you're using 127.0.0.1.nip.io for development, otherwise, change them accordingly. The specifics for what each environment variable does can be found in the configuration section.

.env
...

## ==================== GIS ====================
## The URL to the GIS backend service
GIS_URL=http://gis.127.0.0.1.nip.io

## The URL to the RTUS Server Sent Events service
PUBLIC_RTUS_SEH_URL=http://rtus-seh.127.0.0.1.nip.io

## The name of the distributed map to connect to in RTUS
PUBLIC_GIS_RTUS_MAP_NAME=gis

2.2 Update Vite Configuration​

In order to properly import Cesium, Vite requires additional configuration to copy some required files out from Cesium's node_modules package, as well as an additional CESIUM_BASE_URL variable definition that can be accessed by JavaScript on the browser.

First, install vite-plugin-static-copy:

npm install -D vite-plugin-static-copy@^1.0.6

Then, modify the vite.config.ts file to include 4 necessary folders for Cesium to work properly, as well as the additional CESIUM_BASE_URL definition:

import { normalizePath, searchForWorkspaceRoot } from "vite";
import { viteStaticCopy } from "vite-plugin-static-copy";
const cesium = `${normalizePath(searchForWorkspaceRoot(__dirname))}/node_modules/@cesium`;
const cesiumBaseUrl = "cesium";

import { sveltekit } from "@sveltejs/kit/vite";
import { defineConfig, configDefaults } from "vitest/config";
export default defineConfig({
	plugins: [
		sveltekit(),
		viteStaticCopy({
			targets: [
				{ src: `${cesium}/engine/Build/Workers`, dest: `${cesiumBaseUrl}` },
				{ src: `${cesium}/engine/Source/Assets`, dest: `${cesiumBaseUrl}` },
				{ src: `${cesium}/engine/Source/ThirdParty`, dest: `${cesiumBaseUrl}` },
				{ src: `${cesium}/widgets/Source`, dest: `${cesiumBaseUrl}` },
			],
		}),
	],
	test: {
		include: ["src/**/*.{test,spec}.{js,ts}"],
		exclude: [...configDefaults.exclude, "src/lib/aoh/core/components/ui/*.ts"],
	},
	build: {
		outDir: "build",
	},
	server: {
		allowedHosts: [".localhost", ".127.0.0.1.nip.io"],
	},
	define: {
		CESIUM_BASE_URL: JSON.stringify("/" + cesiumBaseUrl),
	},
});

2.3 Install additional dependencies​

The following additional dependencies, used by some GIS modlet components (that uses shadcn-svelte patterns) requires zod (for validation), formsnap, and sveltekit-superforms.

npm install -D zod formsnap sveltekit-superforms

3. Run the local environment required for GIS development​

dev-containers
podman compose --env-file .env -f gis/compose.yml up -d
tip

Remeber to adjust and add the compose.override.yml if you're using Docker, or have other requirements like exposing the database for direct connection from database management tool.

4. Start the development server​

npm run dev