Development

The project is mainly written in TypeScript and runs in Electron. We recommend using VSCode as an IDE with excellent TypeScript support.

Getting Started

Building and running the application

You need to have NodeJS and a package manager such as Yarn installed. Then run the following commands to get started:

1. Run yarn install to install or update all necessary dependencies.
2. Run yarn dev to build the project files to the /build directory. This will keep running to immediately build changed files when they are updated.
3. In a second terminal, run yarn start to start the application. Refresh the window (Ctrl/Cmd + R) after modifying a file to load the updated build files.

IDE Setup

Linting has been configured with ESLint so that the code style stays consistent (indenting, variable names, use of parentheses, etc.). If you install it as an extension in your IDE, it'll warn you about problems and can automatically fix them in most cases.

Testing

Testing has been configured with Jest. The convention for unit test files is to add them to the same directory as the file you are testing as [filename].test.ts. A short introduction to Jest with Typescript and React can be found here. The official docs include a more in-depth guide.

Tests can be run using yarn test or debugged in VSCode using the launch configs in .vscode/launch.json, which can run either all tests or just the test file that is open. Jest also offers some useful options, such as running yarn test Backend which will only run the test files with Backend in their filename.

The codebase is currently not exhaustively covered by tests. They are therefore not required for contributions, though they are appreciated.

Libraries and frameworks

Name	Function	Description
Electron	Application runtime	Makes it possible to run a website as a desktop application.
ReactJS	UI library	Makes it painless to create interactive UIs. Design simple views for each state in your application, and React will efficiently update and render just the right components when your data changes.
MobX	State management	This is where the application state is managed. Entities fetched from the backend are stored here, actions are used to update them and they are observable so that the UI can update accordingly.
IndexedDB	Database	IndexedDB is built-in to browsers so this was the easiest to configure. A downside is that is only works in the renderer process of Electron. A strong alternative would be SQLite3.

Conventions

Naming

Code

Item	Convention	Example	Exception
modules	kebab-case	menu-items.ts	React Component/class data structure
interfaces	IPascalCase	ISerializable
types	PascalCase	LocationStore
enum variants	PascalCase	enum FileOrder { Asc, Desc }
functions/methods	camelCase	function generateID() { ... }	alternatively: arrow functions
React components	PascalCase	const Outliner = () => { ... }
local variables	camelCase	const myVariable = ...;

Style

Item	Convention	Example	Exception
modules	kebab-case	settings.scss
SASS-variables	$kebab-case	$background-color
CSS-variables	--kebab-case	--background-color
classes	.kebab-case	.button
ids	#kebab-case	#outliner
data attributes	kebab-case	data-dnd

Styling

All styles are defined using SASS. There are two locations where styles are defined:

1. The application style sheets /resources/style: for the layout of panels, global styles, color definitions, etc.
2. The component style sheets /components/*/*.scss: the appearance of buttons, flyouts,

For the application style sheets, there is a file per main panel (toolbar, outliner, content, inspector, etc.) and a couple of files for variable definitions and global styles. To ensure consistent colors are used across the entire application, all of the necessary colors are defined in the colors.scss file. These are then used in the themes.scss file for themes-specific colors (background, font, etc.). The global.scss file contains the root element style, layout definitions and some misc styles like the handlebars.

Publishing a Release

A Github release can be created automatically by creating a tag. This will trigger a Github action. Steps:

1. Update the version in the package.json file (e.g. 1.2.3)
2. Commit that change (git commit -am v1.2.3) and push it (git push)
3. Tag your commit (git tag v1.2.3) and push it as well (git push origin refs/tags/v1.2.3). Note: Make sure your tag name's format is v*.*.*.
4. Once the release pipeline has been completed, publish the draft release on Github, and include the release notes