Skip to content

Latest commit

 

History

History
91 lines (47 loc) · 3.24 KB

CONTRIBUTING.md

File metadata and controls

91 lines (47 loc) · 3.24 KB

Contributing

This document covers how to setup bangle.io locally and also a brief overview of its architecture.

Please, note this document is work in progress 💅 !

Setup

Prerequisites

Local development

  • yarn install to install

  • yarn start to start bangle on localhost:4000

  • yarn jest to run the tests

  • yarn g:e2e to run the integration tests

More commands in the package.json.

Sometimes when running locally, the app might get stuck on loading, this is a known issue, try reloading the page a few times.

Architecture

The repository is divided into multiple smaller node packages which are linked to each other via yarn.

Directory structure

Bangle has the following top level directories containing smaller packages.

  • extensions:All of the first party extensions sit here. If you are fixing a bug or extending a feature, you would likely be editing here.

  • lib: The packages that are shared across the app.

  • js-lib: Independent packages that have no awareness of bangle and have no dependency on any other part of the code.

  • app:The core app that bootstraps everything sits here.

  • worker: Separate directory for any code that will be run the web worker.

  • tooling: Focused on things like integration tests, scripts etc. Any code in here is not bundled in the production app.

Extension file structure

Each extension must have the following top level files:

  • index.ts The entry point for the extension.
  • style.css A single css file containing all the styles of your extension.
  • style.ts: A file which imports the style.css file.

Please note your index.ts file should not import style.ts. This restriction exists to keep the imports within the realms of standard Javascript.

CSS conventions

You are expected to write your own css and not rely on any of the css classes available throughout Bangle as they are internal and subject to change.

Contexts

Bangle uses a concept of context for sharing state across the extensions.

  • action-context for dispatching actions.

  • app-state-context for pending writes, page lifecycle etc.

  • editor-manager-context exposes the Editors.

  • ui-context provides the UI state information, like sidebars, palettes etc.

  • workspace-context: place for centralized workspace ops like fole creation, and deletion etc.

  • extension-registry-context: the glue code for the extension. If you are developing an extension you can ignore this.

Dispatching Actions

Action is a synchronous fire and forget system. If you have used Redux, this is similar to that. If while handling the action a failure occurs, it's up to the handler of the action to show a popup notification to the user or not.

Every handler in the application will be called in the order of their setup. This mechanism exists for other extensions to passively watch an action being dispatched.

WsPaths

A file path in Bangle is denoted by a string with the following syntax:

  • wsPath: A unique string representing a file and its workspace. hello:foo/bar.md.

  • wsName: Workspace name, in hello:foo/bar.md hello is the workspace name.