Skip to content

Getting Started with Codespaces

Jump to bottom
Simon Leech edited this page Oct 1, 2025 · 10 revisions

This guide allows users to get started using XYZ/MAPP right here in the browser.

Prerequisites

  • A GitHub account (required to fork the repository and create a Codespace).
  • No local setup is needed — everything runs directly in your browser using GitHub Codespaces.

1. Create a new fork

While you are able to create a codespace on the public XYZ repository we highly recommend to create a fork of the repository.

The Fork menu is suitable located right between the Watch 👁️ and Star ⭐.
Please give us a quick boost while you are at it. 😉🙏

Alternatively you can create a fork from the GitHub repository URL: https://github.com/GEOLYTIX/xyz/fork

image

You will only need the main branch for this exercise.

image

2. Create a codespace on main

Press on the Code box in the top right - then press Codespaces and Create codespace on main.
image

3. Initial codespace setup

When your Codespace opens, a lightweight version of Visual Studio Code runs directly in your browser. We’ll now set up the environment for XYZ/MAPP.

Run the following commands in the terminal, one by one:

# 1. Check Node.js version (XYZ requires Node.js 22+)
node -v

# If your version is lower than 22, install the latest LTS
nvm install --lts

# Double check the version is now 22+ 
node -v

# 2. Install pnpm (package manager) globally
npm install -g pnpm

# 3. Reinstall dependencies
rm -rf node_modules
pnpm install

# 4. Build the MAPP library
pnpm _build

4. Create a workspace

  • Let's create a workspace.json file in the public directory.
  • The workspace is a JSON document which defines templates, locales, and layers with their properties.
  • We start with this JSON object as content for our workspace.
  • Here, we are simply providing an OpenStreetMap basemap as a single layer on a locale that has access to anywhere in the world.
{
  "locale": {
    "layers": {
      "OSM": {
        "display": true,
        "format": "tiles",
        "URI": "https://{a-c}.tile.openstreetmap.org/{z}/{x}/{y}.png",
        "attribution": {
          "© OpenStreetMap": "http://www.openstreetmap.org/copyright"
        }
      }
    }
  }
}

5. Set the environment

  • We must tell the process environment the location of the workspace.
  • Create a .env file in the root of your repository fork and add the WORKSPACE environment variable WORKSPACE="file:/public/workspace.json".
  • WORKSPACE is the key the application reads to locate your workspace configuration.
  • The value "file:/public/workspace.json" points to a local file path inside your repository.
  • file: tells the application it’s reading from a file locally.
  • /public/workspace.json is the relative path to the JSON file you created in the public folder.
  • This allows the application to load your OpenStreetMap layer (and any other layers you add) from this configuration.
image

6. Create the Launch

  • On the left-hand side of the VSCode window, press the Debug button (or press [Ctrl+Shift+D]).
  • Then press - create a launch.json file, and select Node.js as the debugger.
image
  • This will automatically create the launch.json file for you.
  • You will need to change the program from "${file}" to "express.js".
image
  • Then start the Run and Debug to run the XYZ api with your workspace.
  • You can find the port on which your application runs in the ports tab.
  • Here you can make the port public if you like to open the application on a different browser, share with others or even open on your phone.
image

7. Running the application

  • Opening the codespace port you should see the default Mapp view with an OSM layer displayed.
image

8. Adding a new layer

9. Configuration Time

  • You've got everything set up, now its time to start playing with all the configuration options!
  • All this information can be found in the Workspace Configuration Wiki - specifically the Layer Section

Lots of things to choose from here but a couple of ideas to get you started:

  • Give the layer a clear name.
  • Set edit mode to be off by default and toggleable on.
  • Set the layer to display by default.
  • Give the layer a new field called type and give the user only two editable options 'New' or 'Existing'.
  • Add a theme on this type field.
  • Add filtering to your fields in the infoj.
  • Have a look at some of the plugins available in the lib/ui/plugins folder and their documentation and add them to your MAPP.

10. Optional - deploying to Vercel

Clone this wiki locally