{"id":12130,"library":"terriajs-server","title":"TerriaJS Server","description":"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.","status":"active","version":"4.0.4","language":"javascript","source_language":"en","source_url":"https://github.com/TerriaJS/TerriaJS-Server","tags":["javascript","terriajs","National Map"],"install":[{"cmd":"npm install terriajs-server","lang":"bash","label":"npm"},{"cmd":"yarn add terriajs-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add terriajs-server","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core web framework for handling routes, middleware, and static file serving.","package":"express","optional":false},{"reason":"Provides the coordinate reference system (CRS) lookup service for geospatial transformations.","package":"proj4-cli-defs","optional":false},{"reason":"Middleware for enabling Cross-Origin Resource Sharing (CORS) in the proxy service.","package":"cors","optional":false},{"reason":"Used for rate limiting to protect the server endpoints, addressing security vulnerabilities found in previous rate-limiting solutions.","package":"rate-limiter-flexible","optional":false}],"imports":[{"note":"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.","wrong":"const createTerriaServer = require('terriajs-server');","symbol":"createTerriaServer","correct":"import { createTerriaServer } from 'terriajs-server';"},{"note":"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`.","wrong":"import { startServer } from 'terriajs-server';","symbol":"startServer","correct":"import 'terriajs-server/terriajs-server.js';"},{"note":"While configuration is primarily handled via `serverconfig.json`, TypeScript users may import type definitions for programmatic configuration or validation.","wrong":"import { ServerConfig } from 'terriajs-server';","symbol":"ServerConfig","correct":"import type { ServerConfig } from 'terriajs-server';"}],"quickstart":{"code":"import express from 'express';\nimport path from 'path';\nimport { createTerriaServer } from 'terriajs-server';\n\n// Minimal server configuration - typically read from serverconfig.json\nconst serverConfig = {\n  port: process.env.PORT ?? 3001,\n  public: true,\n  // Define allowed domains for the proxy, crucial for security\n  allowProxyFor: [\n    'https://example.com',\n    'https://another-domain.org'\n  ],\n  // Optional: Share service configuration (e.g., Gist, S3)\n  share: {\n    type: 'gist',\n    accessToken: process.env.GITHUB_GIST_TOKEN ?? '' // Required for Gist\n  },\n  // Other TerriaJS-Server specific configurations go here\n};\n\nasync function startCustomTerriaServer() {\n  try {\n    // createTerriaServer returns an Express application instance\n    const app = await createTerriaServer(serverConfig);\n\n    // Serve static files from a 'wwwroot' directory (e.g., where TerriaMap is built)\n    const wwwrootPath = process.env.WWWROOT_PATH ?? path.join(process.cwd(), 'wwwroot');\n    app.use(express.static(wwwrootPath));\n\n    app.listen(serverConfig.port, () => {\n      console.log(`TerriaJS Server listening on port ${serverConfig.port}`);\n      console.log(`Serving static files from: ${wwwrootPath}`);\n    });\n  } catch (error) {\n    console.error('Failed to start TerriaJS Server:', error);\n    process.exit(1);\n  }\n}\n\nstartCustomTerriaServer();\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade your Node.js environment to version 20.x or 22.x. Check the `engines` field in `package.json` for the exact requirement.","message":"TerriaJS-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.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Migrate your import statements to use ECMAScript Modules (ESM) syntax, e.g., `import { createTerriaServer } from 'terriajs-server';`.","message":"The 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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"PM2 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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"Default 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.","severity":"gotcha","affected_versions":">=4.0.0"},{"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.","message":"Security 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.","severity":"breaking","affected_versions":"<4.0.2"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to use `require()` to import `terriajs-server`, which is an ECMAScript Module (ESM) since version 4.0.0, in a CommonJS context.","error":"ERR_REQUIRE_ESM: require() of ES Module ...terriajs-server/lib/app.js from ... not supported."},{"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.","cause":"The server failed to find its essential configuration file, `serverconfig.json`, at the expected location.","error":"Failed to start TerriaJS Server: Error: The \"config.json\" file does not exist. Please create one."},{"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.","cause":"Despite `terriajs-server` providing a CORS proxy, this error indicates the requested domain for proxying is not allowed by the server's configuration.","error":"CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource."},{"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.","cause":"Another process is already using the default port (3001) that `terriajs-server` attempts to bind to.","error":"Error: Port 3001 is already in use"}],"ecosystem":"npm"}