ZFocus

Manage your time and block distracting websites

Table of Contents

• Intro
• Features
• Structure
  • ChromeExtension
  • Packages
  • Pages
• Installation
  • Chrome
  • Firefox
• Install dependency
  • For root
  • For module
• Environment variables
  • Add new
  • Set via CLI
• Troubleshooting
  • Hot module reload seems to have frozen
  • Imports not resolving correctly
• Community
• Debugging
• Reference

Intro

ZFocus is a Chrome/Firefox extension that helps you manage your time and block distracting websites. Built with React, TypeScript, Vite, and Turborepo for optimal performance and development experience.

Features

• React
• TypeScript
• Tailwindcss
• Vite with Rollup
• Turborepo
• Prettier
• ESLint
• Chrome Extensions Manifest Version 3
• Custom i18n package
• Custom HMR (Hot Module Rebuild) plugin
• End-to-end testing with WebdriverIO

Installation

1. Clone this repository
2. Ensure your node version is >= than in .nvmrc file, recommend to use nvm
3. Install pnpm globally: npm install -g pnpm
4. Run pnpm install
5. Check if you have that configuration in your IDE/Editor:
   • VS Code:
     • Installed ESLint extension
     • Installed Prettier extension
     • Enabled Typescript Workbench version in settings:
       • CTRL + SHIFT + P -> Search: Typescript: Select Typescript version... -> Use Workbench version
       • Read more
     • Optional, for imports to work correctly in WSL, you might need to install the Remote - WSL extension and connect to WSL remotely from VS Code. See overview section in the extension page for more information.
   • WebStorm:
     • Configured ESLint
     • Configured Prettier
     • Optional, but useful File | Settings | Tools | Actions on Save
       -> Optimize imports and Reformat code
6. Run pnpm update-version <version> for change the version to the desired version of your extension.

Important

On Windows, make sure you have WSL enabled and Linux distribution (e.g. Ubuntu) installed on WSL.

Installation Guide

Then, depending on the target browser:

For Chrome:

1. Run:
   • Dev: pnpm dev (on Windows, you should run as administrator; see issue#456)
   • Prod: pnpm build
2. Open in browser - chrome://extensions
3. Check - Developer mode
4. Click - Load unpacked in the upper left corner
5. Select the dist directory from the boilerplate project

For Firefox:

1. Run:
   • Dev: pnpm dev:firefox
   • Prod: pnpm build:firefox
2. Open in browser - about:debugging#/runtime/this-firefox
3. Click - Load Temporary Add-on... in the upper right corner
4. Select the ./dist/manifest.json file from the boilerplate project

Note

In Firefox, you load add-ons in temporary mode. That means they'll disappear after each browser close. You have to load the add-on on every browser launch.

Install dependency for turborepo:

For root:

1. Run pnpm i <package> -w

For module:

1. Run pnpm i <package> -F <module name>

package - Name of the package you want to install e.g. nodemon
module-name - You can find it inside each package.json under the key name, e.g. @extension/content-script, you can use only content-script without @extension/ prefix

How do I disable modules I'm not using?

Read here

Environment variables

Read: Env Documentation

Boilerplate structure

Chrome extension

The extension lives in the chrome-extension directory and includes the following files:

• manifest.ts - script that outputs the manifest.json
• src/background - background script (background.service_worker in manifest.json)
• public - icons referenced in the manifest; content CSS for user's page injection

Important

To facilitate development, the boilerplate is configured to "Read and change all your data on all websites". In production, it's best practice to limit the premissions to only the strictly necessary websites. See Declaring permissions and edit manifest.js accordingly.

Pages

Code that is transpiled to be part of the extension lives in the pages directory.

• content - Scripts injected into specified pages (You can see it in console)
• content-ui - React Components injected into specified pages (You can see it at the very bottom of pages)
• content-runtime - injected content scripts This can be injected from e.g. popup like standard content
• new-tab - override the default New Tab page (chrome_url_overrides.newtab in manifest.json)
• options - options page (options_page in manifest.json)
• popup - popup shown when clicking the extension in the toolbar (action.default_popup in manifest.json)
• side-panel - sidepanel (Chrome 114+) (side_panel.default_path in manifest.json)

Packages

Some shared packages:

• dev-utils - utilities for Chrome extension development (manifest-parser, logger)
• env - exports object which contain all environment variables from .env and dynamically declared
• hmr - custom HMR plugin for Vite, injection script for reload/refresh, HMR dev-server
• i18n - custom internationalization package; provides i18n function with type safety and other validation
• shared - shared code for the entire project (types, constants, custom hooks, components etc.)
• storage - helpers for easier integration with storage, e.g. local/session storages
• tailwind-config - shared Tailwind config for entire project
• tsconfig - shared tsconfig for the entire project
• ui - function to merge your Tailwind config with the global one; you can save components here
• vite-config - shared Vite config for the entire project

Other useful packages:

• zipper - run pnpm zip to pack the dist folder into extension-YYYYMMDD-HHmmss.zip inside the newly created dist-zip
• module-manager - run pnpm module-manager to enable/disable modules
• e2e - run pnpm e2e for end-to-end tests of your zipped extension on different browsers

Troubleshooting

Hot module reload seems to have frozen

If saving source files doesn't cause the extension HMR code to trigger a reload of the browser page, try this:

1. Ctrl+C the development server and restart it (pnpm run dev)
2. If you get a grpc error, kill the turbo process and run pnpm dev again.

Imports not resolving correctly

If you are using WSL and imports are not resolving correctly, ensure that you have connected VS Code to WSL remotely using the Remote - WSL extension.

Reference

• Chrome Extensions
• Vite Plugin
• Rollup
• Turborepo