Firepad
Firepad is an open-source library for adding collaborative capabilities into text and code editors. Firepad uses Google Firebase as a backend, so it requires no server-side code. It supports out of the box popular web editors such as Codemirror, Ace and Monaco.
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, 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 bygrunt). - new adapter to add compatibility with
Codemirror6, arguably one of the best web editor out there. Check the demo here - older
jasminetests now work withjest - basic Typescript support
Status
- The new build system seem to work without any issue. After the
jestrewrite, 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 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. 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) tools.
You also need a project bundler. Rollup and Webpack work fine, but in this tutorial we will use Parcel, 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:
npm i -D @lucafabbian/firepad firebase codemirrorThen, in the same folder, create an index.html file (replace the keys below with your own keys).
index.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:
npx parcel index.htmlAnd open your browser to http://localhost:1234
Enjoy :)
Examples
You can find some Firepad examples here.
You may also visit the original firepad.io to see a live demo of Firepad in rich text mode, or the examples page to see it setup for collaborative code editing.
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:
# 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 changeDatabase 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 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- UsesAnnotationListto 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