The easiest way to get started with TerriaJS is to use TerriaMap. TerriaMap is a full-featured application built on TerriaJS, ready to be customized with your own branding and catalog. It is also a great starting point for more in-depth customization.
This guide explains how to build and run TerriaMap locally. See Deploying to learn how to deploy it for use by others.
You may also be interested in how to make your own map without writing any code.
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/TerriaMap.git cd TerriaMap npm install && npm run gulp && npm start # Open at http://localhost:3001
If you run into trouble or want more explanation, read on.
TerriaJS can be built and run on almost any macOS, Linux, or Windows system. The following are required to build TerriaJS:
- 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 v6.0 or later. v7.x and v8.x are also known to work. You can check your node version by running
node --versionon the command-line.
- npm v3.0 or later. v4.x and v5.x are also known to work. npm is usually installed automatically alongside the above. You can check your npm version by running
The following components are optional:
- GDAL - Used for the conversion service that transforms Esri Shapefiles and other more obscure formats into GeoJSON for display in TerriaJS. This is not required for formats that TerriaJS supports directly, including KML, GeoJSON, etc.
The latest version of TerriaMap is on GitHub, and the preferred way to get it is by using
git clone https://github.com/TerriaJS/TerriaMap.git cd TerriaMap
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.
All of the dependencies required to build and run TerriaMap, other than the prerequisites listed above, are installed using
The dependencies are installed in the
node_modules subdirectory. No global changes are made to your system.
Do a standard build of TerriaMap with:
npm run gulp
Or, you can create a minified release build with:
npm run gulp release
To watch for changes and automatically do an incremental build when any are detected, use:
npm run gulp watch
npm run gulp simply runs
gulp, so you can use that directly if you prefer (run
npm install -g gulp to install it globally).
The full set of
gulp tasks can be found on the Development Environment page.
TerriaMap includes a simple Node.js-based web server, called terriajs-server. To start it, run:
Then, open a web browser on
http://localhost:3001 to use TerriaMap.
Keeping up with Updates
If you're building an application by using TerriaMap as a starting point, you will want to keep in sync as TerriaMap is improved and updated to use new versions of TerriaJS. Forking the TerriaMap repo and using git to keep it in sync is outside the scope of this document, but GitHub has a nice explanation.
After pulling new changes, you will need to run
npm install again to pick up any changed dependencies and then build TerriaMap. If you have problems building or running, it is sometimes helpful to remove and reinstall the dependencies from npm:
rm -rf node_modules npm install