TerriaJS Server

Common errors

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

  cause 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.

  cause 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.

  cause 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

  cause 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.

Warnings

• breaking 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.
  Fix: Upgrade your Node.js environment to version 20.x or 22.x. Check the `engines` field in `package.json` for the exact requirement.
• breaking 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.
  Fix: Migrate your import statements to use ECMAScript Modules (ESM) syntax, e.g., `import { createTerriaServer } from 'terriajs-server';`.
• breaking 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.
  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.
• gotcha 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.
  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.
• breaking 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.
  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.

Install

• npm install terriajs-server npm
• yarn add terriajs-server yarn
• pnpm add terriajs-server pnpm

Imports

• createTerriaServer
  wrong:

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

  correct:

  import { createTerriaServer } from '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
  wrong:

  import { startServer } from 'terriajs-server';

  correct:

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

  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
  wrong:

  import { ServerConfig } from 'terriajs-server';

  correct:

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

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

Quickstart

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();