First clone the repository to a folder.

Linux:

npm install   
npm run build

Windows:

npm install   
npm run build:win

Additionally the following script has to be executed if you want to test it on firefox. Do not execute this if you are using a chromium based browser for testing:

npm run build:webextension:firefox

The userscipt and webextension can then be found in the dist folder.

After the initial build it possible to use one of the following commands for faster and automatic building on file change.

npm run dev:userscript

The extension has 2 separate parts. But the content is probably the most important one for you.

npm run dev:webextension:content
npm run dev:webextension:background

🛑 Please do not update things like the README, because they are autogenerated

You are free to add support for new pages, but you will somewhat be responsible to fix them in the future. The only rule is that we do not add clones or fake websites.

The implementations use ChibiScript, which is a MALSync's domain-specific language for creating website integrations. It compiles down to JSON, making it easy to fix broken implementations without requiring users to wait for a new extension release.

The core of any MALSync integration is the PageInterface. This interface defines all the methods and properties needed to integrate a website. You can find the complete interface definition in:

src/pages-chibi/pageInterface.ts

Study this interface carefully as it's your primary reference for implementation. Each method and property is documented with TypeScript comments explaining its purpose and requirements.

This guide walks you through creating your first working implementation state, which will serve as a starting point.

1. Create a new implementation in src/pages-chibi/implementations/<yourSite>/main.ts:

export const yourSite: PageInterface = {
  name: 'YourSite',
  domain: 'https://yoursite.com',
  languages: ['English'],
  type: 'anime',
  urls: {
    match: ['*://*.yoursite.com/*']
  },
  sync: {
    isSyncPage($c) {
      return $c.url().urlPart(4).boolean().run();
    },
    getTitle($c) {
      return $c.querySelector('.title').text().trim().run();
    },
    getIdentifier($c) {
      return $c.url().urlPart(4).run();
    },
    getOverviewUrl($c) {
      return $c.url().split('/').slice(0, 5).join('/').run();
    
      return $c
        .string(YourSite.domain)
        .concat('/series/')
        .concat($c.this('sync.getIdentifier').run())
        .run();
    },
    getEpisode($c) {
      return $c.url().urlPart(5).regex('episode[_-](\\d+)', 1).number().run();
    }
  },  
  lifecycle: {
    setup($c) {
      return $c.addStyle(require('./style.less?raw').toString()).run();
    },
    ready($c) {
      return $c
        .title()
        .contains('Error 404')
        .ifThen($c => $c.string('404').log().return().run())
        .domReady()
        .trigger()
        .run();
    },
  }
};

2. Add style file in src/pages-chibi/implementations/<yourSite>/style.less:

@import './../pages';

3. Add tests in test/src/pages-chibi/implementations/YourSite/tests.json:

{
  "title": "YourSite",
  "url": "https://yoursite.com",
  "testCases": [
    {
      "url": "https://yoursite.com/watch/123/episode-1",
      "expected": {
        "sync": true,
        "title": "Test Title",
        "identifier": "123",
        "overviewUrl": "https://yoursite.com/watch/123/",
        "nextEpUrl": "https://yoursite.com/watch/123/episode-2",
        "episode": 1,
        "uiSelector": false
      }
    },
    {
      "url": "https://yoursite.com/watch/123/",
      "expected": {
        "sync": false,
        "title": "Test Title",
        "identifier": "123",
        "uiSelector": true,
        "epList": {
          "2": "https://yoursite.com/watch/123/episode-2",
        }
      }
    },
  ]
}

Note: You do not need to verify that the tests work. If they don't work initially, commit them as is. The maintainers will ensure the tests run correctly after the pull request is created. Expect the page tests to fail until the first review.

3. Register your implementation in src/pages-chibi/pages.ts

4. npm run build:webextension to build the extensions

5. Go to the extensions page of the browser (chrome://extensions/), enable Developer mode, click Load unpacked and point it to the folder dist/webextension.

6. The npm run dev:webextension:content command starts a development process that builds your web extension's content scripts, watches for changes in your source files, and automatically rebuilds when changes are detected. You can now proceed with the page implementation. The example implementation provided earlier is the smallest possible implementation, for a more full featured implementation look into the pageInterface in how to extend it.

ChibiScript operations can be chained together, similar to jQuery, with each operation taking the output of the previous one as input. The chain must end with .run() to execute.

The $c object is the entry point for creating ChibiScripts. It provides a fluent interface for chaining operations:

$c.querySelector('.title')  // Find element
  .text()                   // Get text content
  .trim()                   // Remove whitespaces
  .run()                    // Execute the script

All possible chainable ChibiScript functions can be found in the folder src/chibiScript/functions. They are documented and fully typed, meaning you can fully rely on your IDE.

1. Study the PageInterface definition in src/pages-chibi/pageInterface.ts
2. Check existing implementations in src/pages-chibi/implementations/ for examples
3. Join our Discord community and ask in the #programming channel