npm package: @lucafabbian/firepad
Description: Collaborative text editing powered by Firebase - mantained and working fork
Author: Firebase
Latest version: 1.5.20

# Firepad 

[Firepad](http://www.firepad.io/) is an open-source library for adding collaborative capabilities into text and code editors. Firepad uses [Google Firebase](https://groups.google.com/forum/#!forum/firebase-talk) as a backend, so it requires no server-side code. It supports out of the box popular web editors such as [Codemirror](https://codemirror.net/), [Ace](https://ace.c9.io/) and [Monaco](https://microsoft.github.io/monaco-editor/).


### Why this fork?

The original repository is no longer under active development. While Firepad it's still a pretty solid piece of software, it was developed in the early days of javascript. This fork aims to improve the package and make it work with modern libraries, while sticking to the original code as close as possible. Unlike forks such as [firepad-x](https://github.com/interviewstreet/firepad-x), this won't be a complete rewrite (which would take really long time to be stable). It will just provide some nice enhancements/updates/bug fixes and bring the modular approach.


Some major changes:
- code is splitted into pure js 2015 modules, which may be bundled with tools such as `rollup`/`parcel`/`webpack` (instead of relying on a single `<script>` file generated by `grunt`).
- new adapter to add compatibility with `Codemirror6`, arguably one of the best web editor out there. Check the demo [here](https://github.com/lucafabbian/codemirror6-firepad-demo)
- older `jasmine` tests now work with `jest`
- basic Typescript support


### Status

- The new build system seem to work without any issue. After the `jest` rewrite, tests are working again.
- Codemirror6 works, while still missing multicursor display and other minor features.
- Old examples need to be refactored and updated.


## Getting started

#### Setup Firebase

Firepad requires [Firebase](https://firebase.google.com/) in order to sync and store data. Firebase is a suite of integrated products designed to help you develop your app, grow your user base, and earn money. You can [sign up here for a free account](https://console.firebase.google.com/). After creating a new project, you should obtain a `apiKey` and a `databaseURL`.

#### Setup node and rollup

In order to manage javascript dependencies and import Firepad, you have to download the [node + npm (node package manager)](https://nodejs.org/en/download/) tools.

You also need a project bundler. [Rollup](https://rollupjs.org) and [Webpack](https://webpack.js.org/) work fine, but in this tutorial we will use [Parcel](https://parceljs.org/), because it requires no configuration and may be run directly from node, without explicity installing it.

#### Hello Firepad + Codemirror6!

Make a new folder, and install the required dependencies with: 
```js
npm i -D @lucafabbian/firepad firebase codemirror
```

Then, in the same folder, create an `index.html` file (replace the keys below with your own keys).

**index.html**
```html
<!DOCTYPE html>

<script type="module">
  // Import codemirror
  import {EditorView, basicSetup} from 'codemirror'
  // Import firebase
  import firebase from 'firebase/compat/app'
  import 'firebase/compat/database'
  // Import firepad
  import Firepad from '@lucafabbian/firepad'



  // Connect to firebase
  // CHANGE WITH YOUR OWN KEY - this is just a placeholder!!!
  const app = firebase.initializeApp({
      "apiKey": "Oscde395Wsdfgdsfs2n2J43431",
      "databaseURL": "https://my-database.europe-west1.firebasedatabase.app"
  });
  const database = firebase.database(app);


  document.addEventListener("DOMContentLoaded", () => {
    // Create a codemirror6 instance
    const codemirror = new EditorView({
      extensions: [basicSetup ],
      parent: document.body
    })
    // wrap Codemirror 6 with firepad  
    Firepad.fromCodeMirror6(database.ref("firepad-test-database"), codemirror, {
      defaultText: 'hello',
    });
  })
</script>
```

Now just run:
```bash
npx parcel index.html
```
And open your browser to <http://localhost:1234>

Enjoy :)


## Examples

You can find some Firepad examples [here](https://github.com/lucafabbian/firepad/tree/main/examples#readme).



You may also visit the original [firepad.io](http://demo.firepad.io/) to see a live demo of Firepad in rich text mode, or the
[examples page](http://www.firepad.io/examples/) to see it setup for collaborative code editing.

[![a screenshot of demo.firepad.io including a picture of two cats and a discussion about fonts](screenshot.png)](http://demo.firepad.io/)




## Contributing

If you'd like to contribute to Firepad, just create an issue or a pull request. You'll need to do the following to get your environment set up:

```bash
# Download the source code
git clone https://github.com/lucafabbian/firepad.git

# Install dependencies
cd firepad
npm i

# Run tests
# Change with your own api key and database url (this is not a real key) - must be a valid json 
export FIREBASE_CONFIG='{
  "apiKey": "AHdS3A657ufbgfnhnhH8wtXGCzPFqBWYccsdfdfXSas",
  "databaseURL": "https://my-database-default-rtdb.europe-west1.firebasedatabase.app"
}'
npm run test

# Lint/prettify code
npm run prettify


# Build examples
npm run build     # build them for production
npm run examples  # build, serve and rebuild when files change
```


## Database Structure
How is the data structured in Firebase?

* `<document id>/` - A unique hash generated when pushing a new item to Firebase.
    * `users/`
        * `<user id>/` - A unique hash that identifies each user. 
          * `cursor` - The current location of the user's cursor. 
          * `color` - The color of the user's cursor.
    * `history/` - The sequence of revisions that are automatically made as the document is edited.
        * `<revision id>/` - A unique id that ranges from 'A0' onwards.
            * `a` - The user id that made the revision.
            * `o/` - Array of operations (eg TextOperation objects) that represent document changes.
            * `t` - Timestamp in milliseconds determined by the Firebase servers.
    * `checkpoint/` - Snapshot automatically created every 100 revisions.  
        * `a` - The user id that triggered the checkpoint.
        * `id` - The latest revision at the time the checkpoint was taken.
        * `o/` - A representation of the document state at that time that includes styling and plaintext.   

The database structure is exactly the same of the original Firepad repo - 100% compatibility.


## Repo Structure

Here are some highlights of the directory structure and notable source files:


* `examples/` - examples of embedding Firepad.
* `font/` - icon font used for rich text toolbar.
* `src/`
    * `firepad.js` - Entry point for Firepad.
    * `text-operation.js`, `client.js` - Heart of the Operation Transformation implementation.  Based on
      [ot.js](https://github.com/Operational-Transformation/ot.js/) but extended to allow arbitrary
      attributes on text (for representing rich-text).
    * `annotation-list.js` - A data model for representing annotations on text (i.e. spans of text with a particular
      set of attributes).
    * `rich-text-codemirror.js` - Uses `AnnotationList` to track annotations on the text and maintain the appropriate
      set of markers on a CodeMirror instance.
    * `firebase-adapter.js` - Handles integration with Firebase (appending operations, triggering retries,
      presence, etc.).
* `test/` - Jest tests for Firepad (many of these were borrowed from ot.js).
* `vendor/` - Third party files, such as Codemirror5