Installation

# Installation

Geotoolkit provides libraries to be able to leverage ES6 import syntax and are located in bin folder. This folder includes libraries as *.tgz files to be ready to install with npm to node_modules of your application.

It is recommended to use tools such as rollup.js or Webpack, which allow bundling up all of your dependencies automatically and apply tree shaking of your code.

import { Group } from '@int/geotoolkit/scene/Group';
const group = new Group();

# Using GeoToolkit with local .tgz files

If you use .tgz files you can install GeoToolkit in node_modules with npm. The step below shows how to do it:

Modify the package.json to add the GeoToolkit path to dependencies and run npm install.

{
    // ...
    "dependencies": {
        "@int/impl": "file:./GeoToolkit.JS/bin/int-impl-{version}.tgz",
        "@int/geotoolkit": "file:./GeoToolkit.JS/bin/geotoolkit-{version}.tgz",
        "@int/geotoolkit3d": "file:./GeoToolkit.JS/bin/int-geotoolkit3d-{version}.tgz"
    }
}

Usage of the @int/geotoolkit3d classes require adding three.js to the devDependencies, as detailed in this section .

Now you are ready to use @int/geotoolkit and @int/geotoolkit3d``classes classes in your TypeScript or JavaScript code.

# Using Rollup without npm

If you have local installation of GeoToolkit you can create an alias. The step below shows how to do it:

Modify package.json add rollup and rollup-plugin-import-alias

{
    "devDependencies": {
        "rollup-plugin-import-alias": "^1.0.6",
        "rollup": "^1.10.0"
    }
}

Create rollup.config.js and add importAlias to folder with your geotoolkit modules.

import path from 'path';
import importAlias from 'rollup-plugin-import-alias';

export default ({
    plugins: [
        importAlias({
            Paths: {
                '@int': path.resolve(__dirname, 'geotoolkit modules path')
            }
        })
    ]
});

# Using Webpack without npm

If you have local installation of GeoToolkit you can create an alias to GeoToolkit.JS modules. The step below shows how to do it:

Create webpack.config.js and add alias to folder with your geotoolkit modules.

const path = __require_for_vite_Zhmx5e.default || __require_for_vite_Zhmx5e;

module.exports = {
    resolve: {
        alias: {
            '@int': path.resolve(__dirname, 'geotoolkit modules path')
        }
    }
};

# Using NodeJS

To support all features in NodeJS environment geotoolkit requires some additional libraries:

jsdom - implementation of DOM and HTML
Node canvas - Canvas implementation
xmldom - implementation of DOMParser and XMLSerializer

Add them to your package.json

"dependencies": {
    // ...
    "@xmldom/xmldom": "^0.8.1",
    "jsdom": "^26.1.0",
    "canvas": "^3.0.0"
    ...
}

The step below shows how to initialize these libraries for NodeJS:

import '@int/geotoolkit/environment'

# Using Jest

There are some known problems user can face using Jest test system:

1. Need extra libraries like canvas and jsdom (see NodeJS section)

2. Jsdom needs polifill for TextEncoder and TextDecoder, so add it to setup

import { TextEncoder, TextDecoder } from 'util';

Object.assign(global, { TextDecoder, TextEncoder });

3. If Jest throws error like 'unexpected token' and points on an export keyword - follow Jest's advices: set transformer (e.g. ts-jest) and filter for it

 "jest": {
    "transformIgnorePatterns": [
      "node_modules/(?!(@int))/"
    ]
  },

4. To use setup file with TextEncoder workaround and toolkit's initializing for Node from NodeJS section, use dynamic import. Sample CRA setupTests.ts:

import '@testing-library/jest-dom';

import fetchMock from "jest-fetch-mock";
import '@testing-library/jest-dom/extend-expect'
import { TextEncoder, TextDecoder } from 'util';
import 'jest-canvas-mock';

Object.assign(global, { TextDecoder, TextEncoder });
fetchMock.enableMocks();

import('@int/geotoolkit/environment');

# Using npm or yarn

GeoToolkit.JS can be used from npm repository npm.int.com. Get username and password from support@int.com and use it to register with npm

NPM

How to set up @int registry:
Log in with your credentials to @int scope

npm login --registry https://npm.int.com --scope=@int
npm set registry https://npm.int.com --scope=@int

Make sure that only @int scope is enabled for npm.int.com
Edit .npmrc file of your project:

registry=https://registry.npmjs.org/
@int:registry=https://npm.int.com/
//npm.int.com/:_authToken="WHATEVER_TOKEN_GENERATED_BY_NPM"

YARN

Log in to the server using NPM steps described above (NPM section)
Open or create .yarnrc file and modify it in the following way:

always-auth=true
@int:registry=https://npm.int.com/
//npm.int.com/:_authToken="WHATEVER_TOKEN_GENERATED_BY_NPM"

Modify your project package.json and dependencies section and add @int libraries

"dependencies": {
    // ...
    "@int/impl": "{version}",
    "@int/geotoolkit": "{version}",
    "@int/geotoolkit3d": "{version}",
    // ...
}

npm command to find available versions

npm view @int/geotoolkit versions

# Using non-strict d.ts files

Constructors and method setProperties of each class support object in different format, mainly it is lowercase and camelCase. GeoToolkit.JS before version 4.0 was provided with d.ts files which have addition | any. It allows user to call these methods with any case (lower or camel). But because of this the programmer was forced to write code blindly, almost without prompts. Started from 4.0 all public API has been reviewed: we tried to avoid any, Function and object in public API. So when upgrading to 4.0, developers can get a lot of type errors. To make the update smoother we include 'non-strict' version of d.ts files.

To use this version add these lines to 'path' section of your tsconfig.json:


// ...
"@int/geotoolkit/*": ["node_modules/@int/types/geotoolkit/*"],
"@int/geotoolkit": ["node_modules/@int/types/geotoolkit"],
"@int/geotoolkit3d/*": ["node_modules/@int/types/geotoolkit3d/*"],
"@int/geotoolkit3d": ["node_modules/@int/types/geotoolkit3d"]
// ...