Unclutter Development

Thank you for the interest in contributing! This project is open-source because no single person or company can build a reader that works for everyone. If you want a some new feature, the surest way is to implement it yourself :)

Please open an issue if you have any question!

How Unclutter works

The main "trick" is to use a website's responsive style to hide non-essential page elements for us (by parsing & applying these rules in the CSSOM). For other annoyances there are global and site-specific blocklists based on CSS class naming.

To standardize margins, background colors, and font-sizes, the extension also applies custom CSS to text elements it finds in the DOM (with logic to detect what's the main article text). The dark mode feature uses a combination of DOM and CSSOM iterations to darken colors, change the background, or enable a website's native dark mode styles if present.

To tie these (and many more) page modifications together, they each hook into 8 lifecycle phases coordinated from transitions.ts. The major concern here is performance -- minimizing reflows while performing changes stepwise so that they look nice when animated.

Beyond this core functionality there are embedded React iframes to power the social comments & highlights features and the extension settings page, Svelte components for the UI controls including the page outline, and background event handling code to inject scripts into visited pages and handle events.

For documentation on individual features see the docs pages.

Project structure

Besides the Unclutter reader mode extension, this repo also contains code for the Unclutter New Tab extension, a semi-deprecated website for the Unclutter article library, and a serverless Node.js service to generate article screenshots. See the different subfolders of apps.

common contains code shared by two or more of theses apps, notably library-components for UI elements of the Unclutter library, and replicache-nextjs the server-side code to synchronize the library via Replicache.

Development

Install all monorepo dependencies by running yarn install and yarn build at the root of the project.

To develop the Unclutter extension, cd into apps/unclutter and run yarn build to build your code changes. You can then run yarn chrome to start a Chromium window that reloads the extension code every time you build the code (or yarn firefox for Firefox).

For hot reloading of the common packages run yarn dev at the root of the project.

Release process

yarn package inside any of the extension folders generates the bundled .zip extension files. These need to be manually uploaded to the Chrome and Firefox extension stores by @phgn0. For Chrome, extension releases usually take 1-4 days to be approved due to their review process.

The apps/library-web website and apps/serverless-screenshots service are infrequently deployed on demand.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!