Skip to content

Development

Jump to bottom
Joe Meszaros edited this page Jan 15, 2025 · 1 revision

Developer Guide

Welcome to the Speleo Studio Developer Guide! This page is intended for contributors, providing assistance with setting up the development environment and understanding the basic concepts and design principles behind Speleo Studio.

Concepts

Frameworks and Languages

Speleo Studio is a web application built on the foundational technologies of JavaScript, HTML, and CSS. It does not depend on any frontend frameworks like React or Angular, nor does it use high-level JavaScript-based programming languages like TypeScript. Web development is a dynamically evolving field, with significant momentum and frequent changes involving the rise and fall of frontend frameworks and libraries. While popular frameworks may disappear in the next 5-10 years, the core building blocks of web development—vanilla JavaScript, HTML, and CSS—are likely to remain constant. Therefore, Speleo Studio aims to continue functioning effectively in the future.

Dependencies

Utilizing external libraries is typically essential when developing a complex web application, such as a 3D cave visualization software. Speleo Studio relies on the following dependencies:

  • Three.js: A cross-browser JavaScript library and application programming interface (API) used for creating and displaying animated 3D computer graphics in a web browser using WebGL.
  • Tabulator: An easy-to-use interactive table generation JavaScript library.
  • Infinite-tree: A browser-ready tree library capable of efficiently displaying a large amount of data using infinite scrolling.

Leveraging the power and contributions of a community through external libraries is advantageous, but it also means the lifecycle of the library and your application are intertwined. You must maintain your dependencies and find alternatives if the chosen ones are no longer maintained. For this reason, I've aimed to keep external dependencies to a minimum and have invested effort in developing custom solutions and self-written code. There is potential for replacing Infinite-tree due to its relatively simple nature as a JavaScript library.

Package Managers

Given the minimal set of dependencies, I did not find it necessary to use a package manager such as NPM or Yarn.

Offline Development

All dependencies are stored in the 'dependencies' folder, and no HTTP requests are made from Speleo Studio. This allows for offline use and testing, providing a significant advantage for Speleo Studio users who often need to work in isolated environments, like caves.

Browsers

The supported web browsers are Firefox and Chrome. Speleo Studio may work with Edge and Safare but it is not guarenteed!

Setting Up

If you do not already have a GitHub account, please create one, as GitHub is the collaboration platform for Speleo Studio development. Before diving into the development, please read the Airbnb JavaScript Style Guide to ensure a consistent development process.

First, you need to check out (clone) the code from the Speleo Studio GitHub repository [https://github.com/joemeszaros/speleo-studio] to your local development environment. You can easily do this with the following command:

git clone git@github.com:joemeszaros/speleo-studio.git

There are alternative methods for checking out the repository; please make sure you choose the one that best suits your needs.

The following tools are used to ensure that the source code is well-formatted and adheres to the style guide:

  • Prettier: A code formatter that integrates with most editors.
  • ESLint: A linter that statically analyzes your code to quickly identify problems. It is integrated into most text editors.

The configuration file for Prettier is .prettierrc.json, and for ESLint, it is eslint.config.mjs.

Local environment

In order to test and run Speleo Studio in a local environment (your laptop) you need to start an HTTP server that could host Spele Studio files, like index.html. There are plenty of HTTP servers that you can run locally, for me Python was the easiest choice:

python3 -m http.server 8000

Editor

I recommend using a modern editor or IDE that supports fast and easy development, integrates well with ESLint and Prettier, and optionally supports AI code generation, like Copilot. If you choose an editor other than Visual Studio Code, please add the setup steps here.

Visual Studio Code

Visual Studio Code (VS Code) is a popular and user-friendly editor for web development. Once installed, please add the following extensions:

With the Prettier extension installed, you can format your code using the Format Document command. This command enhances consistency by adjusting spacing, line wrapping, and quotes.

To open the command palette, use COMMAND + SHIFT + P on macOS or CTRL + SHIFT + P on Windows. In the command palette, search for "format" and then select Format Document.

So far, you have needed to manually run the command to format your code. To automate this process, you can enable a setting in VS Code to format your files automatically when saved. This ensures that unformatted code doesn't end up in version control.

To change this setting, press COMMAND + , on macOS or CTRL + , on Windows to open the Settings menu. Once the menu is open, search for Editor: Format On Save and ensure that option is checked. Once this is set, you can write your code as usual, and it will be automatically formatted upon saving.

The ESLint extension uses the ESLint library installed in the opened workspace folder. If the folder doesn't provide one, the extension looks for a globally installed version. If you haven't installed ESLint either locally or globally, do so by running npm install eslint in the workspace folder for a local installation or npm install -g eslint for a global installation.

You can run the linter with the following command:

npx eslint src/**

Debugging

There are multiple ways for debugging Speleo Studio. You can either use the build in Developer Tool of you web browser or attach your editor/IDE to a running web browser. If you prefer the built in Developer Tools please find guides and materials on the internet.

To attach e.g. VS Code to a running Chrome instance you should start Chrome in debug mode:

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 "http://localhost:8000"

Create the following launch.json in your .vscode folder :

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Launch localhost",
      "type": "chrome",
      "request": "attach",
      "port": 9222
    }
  ]
}

and you can start your debugging session by setting breakpoints in VS Code and pause execution.

Clone this wiki locally