Skip to content

Cloning and Building

If you've done this sort of thing before, you'll find it easy to clone and build TerriaMap with these quick instructions:

git clone https://github.com/TerriaJS/terriajs.git

cd terriajs

corepack enable   # or install pnpm: https://pnpm.io/installation

export NODE_OPTIONS=--max_old_space_size=4096

pnpm install && pnpm dev

# Open at http://localhost:3001

If you run into trouble or want more explanation, read on.

The Terria monorepo

TerriaJS and TerriaMap now live together in a single pnpm + Turborepo monorepo:

  • packages/terriajs — the TerriaJS library.
  • packages/terriajs-server — the small Node web server that serves the built map.
  • apps/terriamap — TerriaMap, the reference application (package name terriajs-map).

You clone the one repo and work on any of them from the root. See the monorepo overview for the full task list.

Prerequisites

TerriaJS can be built and run on almost any macOS, Linux, or Windows system. The following are required:

  • The Bash command shell. On macOS or Linux you almost certainly already have this. On Windows, you can easily get it by installing Git for Windows. In the instructions below, we assume you're using a Bash command prompt.
  • Node.js v22 or later. The repo pins the version used for development in .nvmrc. Check with node --version.
  • pnpm 12.x. Install it by following pnpm's installation guide, or run corepack enable if you have Corepack available.

Cloning the monorepo

The latest version is on GitHub, and the preferred way to get it is by using git:

git clone https://github.com/TerriaJS/terriajs.git

cd terriajs

If you're unable to use git, you can also download a ZIP file and extract it somewhere on your system. We recommend using git, though, because it makes it much easier to update to later versions in the future.

Increase NodeJS memory limit

To avoid running out of memory when installing dependencies and building, increase the memory limit of node:

export NODE_OPTIONS=--max_old_space_size=4096

Installing dependencies

All of the dependencies for every package in the workspace are installed from the repo root with a single command:

pnpm install

The dependencies are installed into per-package node_modules directories linked from a central store. No global changes are made to your system.

Building and running

The everyday loop builds TerriaMap (and the TerriaJS it depends on), watches for changes, and serves the result on http://localhost:3001:

pnpm dev

To run the workspace build scripts once (TerriaMap is built without minification):

pnpm build

To build and then serve the built map (without watching):

pnpm start

To produce a minified release build of the app specifically:

pnpm --filter terriajs-map exec gulp release

The full set of gulp tasks can be found on the Development Environment page.

Keeping up with updates

Stop any running watch processes before removing dependencies.

Pull the latest changes with git pull, then run pnpm install again to pick up any changed dependencies before rebuilding. If you have problems building or running, it is sometimes helpful to remove and reinstall the dependencies:

rm -rf node_modules packages/terriajs/node_modules packages/terriajs-server/node_modules apps/terriamap/node_modules
pnpm install

Having trouble?

Checkout the Problems and Solutions page to see if we have them covered. You are also welcome to post your problem on the TerriaJS Discussions forum and we'll be happy to help!

Next Steps

Now that you have a working local build of TerriaMap, you may want to customize it or deploy it for others to use.