DOCSEARCHbyAlgolia
Submit Docs

Floccus Documentation

repository·develop·Indexed 27 days ago

https://github.com/floccusaddon/floccus

A tool for privately syncing native browser bookmarks across different browsers and devices. It supports various sync providers including Nextcloud, Linkwarden, KaraKeep, Google Drive, Dropbox, Git servers, and WebDAV-compatible services. Documentation covers installation, development environment setup for the browser extension and Android app, and guidelines for implementing custom sync adapters using the Resource API.

Tokens
7.1K
Snippets
18
Records
42
Agent score
93%

What's inside Floccus

  1. Understand Floccus synchronization goals and behavior

    develop

    Floccus is designed as an open, cross-platform synchronization solution for browser data using a self-hosted server.

    Key behavioral characteristics:

    • Eventual Consistency: The system prioritizes eventual consistency across all sites over intention preservation. If a synchronization error occurs, the system is designed to ensure all sites eventually reach a consistent state, though manual resolution may be required.
    • Sync Timing: To prevent premature synchronization (which can cause repeated syncs and spread inconsistencies), Floccus employs a timeout mechanism to wait until all pending bookmark operations are completed before triggering a sync.

  2. Set up a Floccus development environment

    develop

    To develop Floccus, follow these steps:

    1. Clone the repository.
    2. Install the latest LTS version of Node.js.
    3. In the root of the repository, run npm install.
    4. Run npm run build to build the project.

    Note for Windows users: If you encounter a gulp error during the first build, install it globally using npm install -g gulp after running the initial npm install in the repo root.

    npm install
npm run build

  3. Develop the Floccus Android app

    develop

    To build the Android application:

    1. Ensure you have Android Studio installed.
    2. Open the android/ folder in Android Studio.
    3. Build the app using standard Android Studio procedures.
    4. Use npm run build and npm run watch in the root directory to push changes to the android/ folder as necessary.

  4. Render the Options UI using JSX

    develop

    Floccus uses a React-style virtual DOM with JSX for rendering adapter configuration screens. Use the static renderOptions(state, update) method to define your UI.

    To ensure your UI matches the Floccus design, import standard components from the basics module.

    Example Implementation

    import * as Basics from '../components/basics'
const { Input, Label, OptionSyncFolder } = Basics

static renderOptions(state, update) {
  let data = state.account
  let onchange = (prop, e) => {
    update({ [prop]: e.target.value })
  }
  return (
    <form>
      <Label for="url">Nextcloud URL</Label>
      <Input
        value={data.url}
        type="text"
        name="url"
        oninput={(e) => onchange('url', e)}
      />
      <OptionSyncFolder account={state.account} />
    </form>
  )
}
    import * as Basics from '../components/basics'
const {
  Input,
  Button,
  Label,
  OptionSyncFolder,
  OptionDelete,
  OptionResetCache,
  OptionParallelSyncing,
  OptionSyncInterval,
  OptionSyncStrategy,
  H3
} = Basics

// Usage in renderOptions
static renderOptions(state, update) {
  let data = state.account
  let onchange = (prop, e) => {
    update({ [prop]: e.target.value })
  }
  return (
    <form>
      <Label for="url">Nextcloud URL</Label>
      <Input
        value={data.url}
        type="text"
        name="url"
        oninput={(e) => onchange('url', e)}
      />
      <OptionSyncFolder account={state.account} />
    </form>
  )
}

  6. Internationalize Adapter UI strings

    develop

    To make your adapter's UI translatable:

    1. Add your strings to _locales/en/messages.json using a unique ID.
    2. Use the browser.i18n.getMessage API to retrieve them.
    import browser from '../browser-api'

const label = browser.i18n.getMessage('LabelNextcloudurl')
    import browser from '../browser-api'

// ....

browser.i18n.getMessage('LabelNextcloudurl')

  7. Run and test the browser extension locally (Firefox)

    develop

    Follow these steps to test the extension in Firefox. Warning: Use a dedicated Firefox profile to avoid destroying your existing bookmarks and tabs.

    1. Build the extension: Run npm run build-release (or npm run build-release-win on Windows).
    2. Prepare for testing: Copy RepoRoot/dist/js/test.js into the release package at FloccusPackage.xpi/dist/js/test.js.
    3. Setup Profile: Go to about:profiles in Firefox to create/manage a dedicated test profile.
    4. Load Extension: In the dedicated profile, go to about:debugging, select "This Firefox", and under "Temporary Extensions", select "Load Temporary Add-on..." and pick your .xpi file.
    5. Run Tests:
      • Click "Manifest URL" in the extension settings to get a URL like moz-extension://<GUID>/manifest.json.
      • Replace manifest.json with dist/html/test.html (e.g., moz-extension://<GUID>/dist/html/test.html) and press Enter.
    6. Debug: Press F12 to open developer tools and use the "Debugger" tab to set breakpoints.

  8. Build and watch Floccus

    develop

    Use the following npm scripts to manage builds:

    • Standard Build: npm run build
    • Watch Mode (Auto-compile): npm run watch (automatically compiles changes as you make them).

    Windows-specific scripts:

    • Build: npm run build-win
    • Watch: npm run watch-win
    • Release: npm run build-release-win
    npm run build
npm run watch

  9. Install Floccus for browser bookmark syncing

    develop

    Floccus allows you to sync native browser bookmarks privately across different browsers and devices. It supports various sync providers including Nextcloud Bookmarks, Linkwarden, KaraKeep, Google Drive, Dropbox, Git servers (GitHub, GitLab, Gitea, etc.), and any WebDAV-compatible service.

    To get started, download the extension for your preferred browser from the official download page.

    https://floccus.org/download

  10. Manage bookmark and folder tree structures

    develop

    Floccus uses Bookmark and Folder classes to represent bookmark tree nodes. These classes support hierarchical structures, indexing for fast lookups, and serialization.

    • Bookmark: Represents an individual bookmark with a title, url, id, and tags.
    • Folder: Represents a container that holds children (which can be Bookmark or Folder instances).
    • TItem: A union type of Bookmark<L> | Folder<L>.
    • ItemLocation: Defines where the item resides, either ItemLocation.LOCAL or ItemLocation.SERVER.

  11. Troubleshoot Nextcloud sync errors (Error code 500)

    develop

    If you are syncing to Nextcloud and encounter an Error code 500, it may be due to MySQL or MariaDB not supporting emojis by default.

    To resolve this:

    1. Check your Nextcloud logs for SQL errors.
    2. If you see charset errors, follow the official Nextcloud documentation to enable 4-byte character support for your database.

  12. Avoid using Firefox Sync with Floccus

    develop
    It is discouraged to use Firefox Sync simultaneously with Floccus. This is because the WebExtensions bookmarks API allows Record GUIDs to change, and these changes are only detectable when Firefox Sync is in use. Using both services together can lead to unexpected behavior due to these GUID modifications.