Registry / web-framework / terriajs-server

terriajs-server

library4.0.4jsnpmunverified

TerriaJS-Server is a foundational Node.js Express server designed to complement the TerriaJS geospatial platform. It provides essential backend services for web-based 2D and 3D geospatial data explorers, including a robust CORS proxy for accessing data providers that lack proper CORS headers, a `proj4` Coordinate Reference System (CRS) lookup service, an `ogr2ogr` conversion service for unsupported geospatial vector data formats (like shapefiles) to GeoJSON, and services for persistent sharing of map configurations. Currently at stable version 4.0.4, published recently, the package undergoes active maintenance with updates driven by the needs of the broader TerriaJS ecosystem. Its key differentiators lie in its specialized geospatial services and deep integration with TerriaJS and TerriaMap, enabling rich, interactive mapping applications, particularly within the context of National Map projects.

web-framework http-networking data devops

npm install terriajs-server

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TERRIAJS-SERVER

terriajs-server

web-frameworkjavascriptv4.0.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createTerriaServer

✓ import { createTerriaServer } from 'terriajs-server';

✗ const createTerriaServer = require('terriajs-server');

Since version 4.x (and Node.js >=20.0.0 requirement), `terriajs-server` is an ESM-first module. Use `import` statements. The default export is a function to create an Express app instance.

startServer

✓ import 'terriajs-server/terriajs-server.js';

✗ import { startServer } from 'terriajs-server';

To run the server directly via its CLI entry point, you can import the side-effectful script. This is equivalent to running `node terriajs-server.js` or `npm start`.

ServerConfig

✓ import type { ServerConfig } from 'terriajs-server';

✗ import { ServerConfig } from 'terriajs-server';

While configuration is primarily handled via `serverconfig.json`, TypeScript users may import type definitions for programmatic configuration or validation.

Demonstrates programmatic initialization and startup of the TerriaJS Server with a basic configuration, including static file serving and environment variable usage for secrets. This is useful for embedding or custom deployments.

import express from 'express'; import path from 'path'; import { createTerriaServer } from 'terriajs-server'; // Minimal server configuration - typically read from serverconfig.json const serverConfig = { port: process.env.PORT ?? 3001, public: true, // Define allowed domains for the proxy, crucial for security allowProxyFor: [ 'https://example.com', 'https://another-domain.org' ], // Optional: Share service configuration (e.g., Gist, S3) share: { type: 'gist', accessToken: process.env.GITHUB_GIST_TOKEN ?? '' // Required for Gist }, // Other TerriaJS-Server specific configurations go here }; async function startCustomTerriaServer() { try { // createTerriaServer returns an Express application instance const app = await createTerriaServer(serverConfig); // Serve static files from a 'wwwroot' directory (e.g., where TerriaMap is built) const wwwrootPath = process.env.WWWROOT_PATH ?? path.join(process.cwd(), 'wwwroot'); app.use(express.static(wwwrootPath)); app.listen(serverConfig.port, () => { console.log(`TerriaJS Server listening on port ${serverConfig.port}`); console.log(`Serving static files from: ${wwwrootPath}`); }); } catch (error) { console.error('Failed to start TerriaJS Server:', error); process.exit(1); } } startCustomTerriaServer();

Debug

Known issues

breakingTerriaJS-Server now requires Node.js version 20.0.0 or higher (for v4.x) and 22.0.0 or higher (for v5.x-alpha). Running with older Node.js versions will result in errors.

fix

Upgrade your Node.js environment to version 20.x or 22.x. Check the `engines` field in `package.json` for the exact requirement.

affects: >=4.0.0

breakingThe package has transitioned to an ESM-first module. CommonJS `require()` statements for the main package entry point will no longer work, leading to `ERR_REQUIRE_ESM` errors.

fix

Migrate your import statements to use ECMAScript Modules (ESM) syntax, e.g., `import { createTerriaServer } from 'terriajs-server';`.

affects: >=4.0.0

breakingPM2 is no longer officially supported for running `terriajs-server`, and the default `npm start` script now runs the server in the foreground. Existing PM2 configurations may need adjustment or replacement.

fix

Remove PM2 from your deployment strategy for `terriajs-server`. Use native `node` commands, or container orchestration tools like Docker/Kubernetes directly. For development, `npm start` runs in the foreground.

affects: >=4.0.0

gotchaDefault proxy domains in `serverconfig.json` are largely deprecated and will be removed in future releases. Relying on these pre-configured domains without explicit custom configuration is risky.

fix

Explicitly define all domains for which the proxy service should be active within your custom `serverconfig.json` file under the `allowProxyFor` array. Always review and update this configuration for security and functionality.

affects: >=4.0.0

breakingSecurity vulnerabilities in the proxy endpoint (CVEs) have been addressed by replacing `express-brute` with `rate-limiter-flexible` and fixing a bug that allowed requests to unintended domains.

fix

Upgrade `terriajs-server` to version 4.0.2 or higher to benefit from these crucial security fixes. Review your `allowProxyFor` configuration carefully to prevent unintended proxying.

affects: <4.0.2

Errors

Common errors & fixes

ERR_REQUIRE_ESM: require() of ES Module ...terriajs-server/lib/app.js from ... not supported.

Attempting to use `require()` to import `terriajs-server`, which is an ECMAScript Module (ESM) since version 4.0.0, in a CommonJS context.

fix

Change your import statement to use ESM syntax: `import { createTerriaServer } from 'terriajs-server';` or `import createTerriaServer from 'terriajs-server';` if it's a default export.

Failed to start TerriaJS Server: Error: The "config.json" file does not exist. Please create one.

The server failed to find its essential configuration file, `serverconfig.json`, at the expected location.

fix

Copy `serverconfig.json.example` (or `devserverconfig.json`) from the package's root or documentation to `serverconfig.json` in your project's root and configure it according to your needs. Ensure the server has read access to this file.

CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

Despite `terriajs-server` providing a CORS proxy, this error indicates the requested domain for proxying is not allowed by the server's configuration.

fix

Edit your `serverconfig.json` file and add the domain of the problematic resource to the `allowProxyFor` array. Ensure the URL scheme (HTTP/HTTPS) and domain exactly match.

Error: Port 3001 is already in use

Another process is already using the default port (3001) that `terriajs-server` attempts to bind to.

fix

Change the `port` in your `serverconfig.json` or pass the `--port` option when starting the server (e.g., `npm start -- --port 8000`) to use an available port. Kill the conflicting process if it's unintentional.

Upgrade

Version history

4.0.4latest on npm

Audit

Dependencies

expressrequiredCore web framework for handling routes, middleware, and static file serving.

proj4-cli-defsrequiredProvides the coordinate reference system (CRS) lookup service for geospatial transformations.

corsrequiredMiddleware for enabling Cross-Origin Resource Sharing (CORS) in the proxy service.

rate-limiter-flexiblerequiredUsed for rate limiting to protect the server endpoints, addressing security vulnerabilities found in previous rate-limiting solutions.

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/TerriaJS/TerriaJS-Server ↗

packagehttps://www.npmjs.com/package/terriajs-server ↗

homepagehttps://terria.io ↗