Building a Chrome Extension with React (Gachon-Tools)

I developed a Chrome extension that lets you view all your assignments at a glance on Gachon University's Cyber Campus.

Chrome Extension Store

You can also check it out on GitHub.

Why I Built This

Last year, when COVID restrictions had just been lifted, our university was running classes with a mix of in-person and online sessions.

At one point, a professor canceled class and replaced attendance with a recorded lecture.

At the time, I was taking 21 credits, and between other assignments and tasks, I completely forgot that I had a recorded lecture to watch. The deadline was before the next class session, and I was sitting in the classroom relaxed when a friend next to me asked if I had watched the lecture -- that's when I suddenly remembered.

I ended up being marked as late, and while I felt it was unfair, I had no excuse since it was my own fault for forgetting.

There must be quite a few students like me who forgot about assignments, missed recorded lectures, or failed to submit their work. Especially for students taking many credits, managing assignments must be even harder. So I decided to build an extension that lets you see at a glance what assignments you need to do and when they're due.

How Do You Build an Extension?

To build a Chrome extension, you need to understand how it's structured.

manifest.json - A specification file containing the manifest version, extension name, version, etc.

background - A script that runs as a service worker, responding to browser events

content script - A script that can be directly injected into web pages

popup - The popup window that appears when you click the extension icon

option - The page that appears when you click settings in the extension management page

Can You Build Extensions with React?

Using a Boilerplate

Fortunately, there was a boilerplate available, so I used it as a reference for the setup.

Warning

Content scripts run in a safe js environment, meaning an isolated space where ES Modules cannot be used, so you need to use dynamic imports. Reference

The boilerplate was structured this way for that reason.

// pages/content/index.ts
import('./main');

export {};

// pages/content/main.tsx
import Content from '@pages/content/Content';
import { createRoot } from 'react-dom/client';

const root = document.createElement('div');
root.id = 'root';

document.body.appendChild(root);

createRoot(root).render(<Content />);

It uses import() for dynamic importing to access main.tsx.

Problem 1: Error When Code Splitting with React.Lazy

I used React's lazy for code splitting to enable Suspense functionality, but when I built and tested it, an error occurred.

ERROR: Expected ")" but found "."

The dynamicImport shown in the error was something converted by a custom plugin in the boilerplate, and the error was caused by that plugin.

import type { PluginOption } from 'vite'

export default function customDynamicImport(): PluginOption {
  return {
    name: 'custom-dynamic-import',
    renderDynamicImport() {
      return {
        left: `
        {
          const dynamicImport = (path) => import(path);
          dynamicImport(
          `,
        right: ')}',
      }
    },
  }
}

It seems the error occurred because it wraps with curly braces at the end.

Attempt 1 - Disabling the Plugin (Resolved)

So I proceeded without applying this plugin, and that particular error disappeared. However, the next error appeared immediately.

Problem 2: Browser Console Error Saying exports Cannot Be Read When Testing the Extension

1. Is this an error caused by customizing the build through Vite's rollupOptions? (No)

• Removed rollupOptions and tested with just the bundled files and a manually written manifest -> Same error occurred

2. Is additional configuration needed? (Partially)

• What if I set the base configuration in vite.config so that asset files are read correctly?

// vite.config.js
export default defineConfig({
  build: {
    base: './',
    rollupOptions: {
      // ...
    },
  },
})

After specifying the base root like this and bundling, another error appeared because the entry file was using import.meta.url.

// content script entry file
const __vitePreload = function preload(baseModule, deps, importerUrl) {
  //...
}

__vitePreload(
  () => import('../../../assets/js/main.096ede36.js'),
  true ? ['../../../assets/js/main.096ede36.js', '../../../assets/js/client.8f342e30.js'] : void 0,
  import.meta.url
)

Attempt 1: Creating a Custom Plugin

I looked into whether there was a way to change that by digging through the Vite documentation and the Rollup documentation.

After a long search, I found a hook called resolveImportMeta in Rollup. This hook allows you to directly manipulate import.meta used in ES Modules.

import.meta.url provides the full URL of the module, and to point it to the extension's file path, you can use chrome.runtime.getURL. I created a custom plugin like this:

import type { PluginOption } from 'vite'

export default function resolveMetaChromeExtension(): PluginOption {
  return {
    name: 'resolve-meta-chrome-extension',
    resolveImportMeta: (property) => {
      if (property === 'url') {
        return 'chrome.runtime.getURL("")'
      }
    },
  }
}

Applying this plugin resolved the error caused by the base root, but the original export issue from the first error still remained.

Attempt 2: Setting build.modulePreload to false in Vite Config (Resolved)

Vite pre-caches modules during the build. So Vite exports a function called __vitePreload in the entry file, which handles module preloading automatically. This causes an error because, as mentioned in the warning above, ESM cannot be used in the entry file.

Why did the error occur when using React.Lazy?

The entry file imports main.tsx, and main.tsx renders App.tsx.

However, since Lazy dynamically imports components, it needs to access the __vitePreload function in the entry file. That's why Vite exports that function from the entry file.

const A = reactExports.lazy(() =>
  __vitePreload(
    () => import('./A-192aa1d7.js'),
    true
      ? ['assets/A-192aa1d7.js', 'assets/globals-0034e337.js', 'assets/globals-14f4290f.css']
      : void 0
  )
)

What is vitePreload?

There was an explanation in the official documentation.

Vite automatically transforms Direct Import statements to <link ref="modulepreload"> during the build to pre-cache modules.
When the module is needed, it can be used immediately.

The "Direct Import" mentioned here seems to refer to dynamic imports.

It literally pre-loads modules by caching them in advance.

Vite allows configuring modulePreload as a build option, which resolved the issue above.

Using the CRXJS Library

Until deploying the MVP, I used the boilerplate for setup, but there were some cumbersome aspects, so I switched to the Vite plugin provided by the CRXJS library.

Using this library provided many benefits.

1. Being able to use Vite's HMR feature sped up development

• Build -> start dev and load the extension, then you can see changes immediately whenever something is modified.

2. No longer needed to separately update the version in both package.json and manifest.json when the extension version is updated

• Only package.json needs to be changed.

• Since the manifest is automatically generated during the build, management became much easier.

How Should the UI Look? I Want It to Be as Non-intrusive as Possible...

1. The first location I considered was where the course list is shown on the main page.

I wanted to place it right below View All Courses, but the course list would be pushed down, so I passed on that.

2. Bottom-right corner of the page

I thought it would be nice to create a circular button in the bottom-right corner like Channel Talk, showing a modal when clicked.

But there was already a TOP button in the bottom-right corner that scrolls to the top, which would ruin the UI. Pass on this too.

3. Bottom-center of the page

Similar to option 2, but placed at the bottom-center with a modal appearing when clicked. I placed it where it would be easy to click while being as non-intrusive as possible to users.

The position wasn't perfect, but I went with this approach for now. (Planning to update so users can customize the button position later.)

When I actually used it, the small circle was surprisingly hard to click. So I made the circle expand horizontally when you hover over it, widening the clickable area.

The animation was easily implemented using the Framer-motion library.

Additionally, I used the same library to create smooth effects for when the modal appears and disappears, and when filters are toggled on and off.

Fetching Assignment Data

Initially, I fetched page documents via GET requests and parsed the data manually using JavaScript's built-in methods.

However, as the amount of data to fetch grew and some parts became difficult to manipulate, I switched to using the cheerio library.

Crawling Logic

1. Get the id and title from the My Courses page on Cyber Campus

2. Use the course id to fetch the document of that course page and extract the desired information (assignments, recorded lectures)

Problem 1: The Course Page Doesn't Show Submission/Viewing Status!

Fortunately, there was a separate assignment page, so I crawled that page. However, the start date wasn't available there, so I mapped the data from the course page with the data from the assignment page using the id value.

Problem 2: Can't Get Recorded Lecture IDs from the Recorded Lecture Page

By comparing the viewing time and the required attendance time on the Learning Progress or Online Attendance page, you could get this information, but the problem was that I couldn't get the id of the specific recorded lecture.

So I couldn't map them using a unique value like I did with assignments.

Attempt 1: Mapping by Recorded Lecture Title

At first, I mapped by title value. At least for the courses I was taking, there were no cases of duplicate recorded lecture titles, so it worked fine during testing. I think I just assumed it would work fine even if assignment titles were the same.

But of course, the problem eventually surfaced. Several users reported issues through feedback, saying the viewing status of recorded lectures was being marked incorrectly.

Even from the screenshots, the crawling logic seemed fine, so I was puzzled. Fortunately, a friend who was taking that course let me test with their account, and I discovered the issue was in this part.

Attempt 2: Mapping by Recorded Lecture Title + Week Title

Since there was no unique value, I had no choice but to go with this approach. The week title was the data that had the least overlap.

I retrieved the data-original-title value and added it to the recorded lecture data,

and added the week title from the course page to the recorded lecture data, then mapped the two datasets by recorded lecture title + week title.

However, if there are recorded lectures with the same title in the same week, it becomes problematic.

In such cases, I think the solution would be to let users manually modify the viewing status.

Deployment

Deployment is simply done by compressing the bundled files and uploading them. After the initial deployment, instead of immediately promoting on Everytime (the university community), I spent a few days only promoting to friends for testing.

As expected, there were quite a few bugs, which gave me plenty of opportunities to refactor.

Introducing Sentry

Before promoting on Everytime, I introduced Sentry, an error logging system, to catch any potential errors. It not only tracks where errors occur but also provides features like replaying user actions as video before the error happened.

The setup was straightforward.

Just do the init setup and error logs start accumulating when errors occur. I wrapped it with Sentry's ErrorBoundary so that a Toast would appear when an error occurs.

Sentry.init({
  dsn: import.meta.env.VITE_APP_SENTRY_DSN,
  environment: import.meta.env.MODE,
  release: version,
  integrations: [
    new Sentry.Integrations.Breadcrumbs({ console: true }),
    new Sentry.BrowserTracing(),
  ],
  tracesSampleRate: 1.0,
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
})

import { ErrorBoundary } from '@sentry/react'
import { motion } from 'framer-motion'
import { useRef, useState } from 'react'

import ContentModal from '@/components/domains/ContentModal'
import Toast from '@/components/uis/Toast'
import Portal from '@/helpers/portal'

export default function App() {
  const [isModalOpen, setIsModalOpen] = useState(false)
  const modalRef = useRef()

  const handleModalClick = (event: React.MouseEvent) => {
    if (event.target === modalRef.current) setIsModalOpen(false)
  }

  return (
    <div className="fixed bottom-[25px] left-1/2 translate-x-[-50%]">
      <motion.div
        initial={{ width: '40px', height: '40px' }}
        whileHover={{ width: '100px', height: '50px' }}
        className="cursor-pointer rounded-[50px] bg-[#2F6EA2] shadow-md shadow-[#2F6EA2]"
        onClick={() => setIsModalOpen((prev) => !prev)}
      ></motion.div>
      <Portal elementId="modal">
        <ErrorBoundary fallback={<Toast message="An error has occurred." type="error" />}>
          <ContentModal ref={modalRef} onClick={handleModalClick} isOpen={isModalOpen} />
        </ErrorBoundary>
      </Portal>
    </div>
  )
}

I also used captureException to receive logs for identifying edge cases during the crawling process.

if (!id) {
  captureException(
    new Error(`getVideoAtCourseDocument: id is missing. ${title} / ${startAt} / ${endAt}`)
  )
}

However, since I didn't have a separate admin account, I couldn't accurately identify errors. Currently, I'm only using it to check for edge cases.

Deployment Automation (Github Actions)

It was cumbersome to compress and deploy manually with every version update. So I automated the process. I implemented it using an Action that handles uploads.

name: Publish

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    name: Publish webextension
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 16.x
      - name: Build
        run: |
          yarn install
          yarn build
      - name: Make zip file
        run: zip -r ./build.zip ./dist
        shell: bash
      - name: Upload & release
        uses: mnao305/chrome-extension-upload@v4.0.1
        with:
          file-path: ./build.zip
          extension-id: 'ogldncimhepjdfadhjjhkchknloncnmg'
          client-id: ${{ secrets.CLIENT_ID }}
          client-secret: ${{ secrets.CLIENT_SECRET }}
          refresh-token: ${{ secrets.REFRESH_TOKEN }}

Now a tag push automatically handles the deployment, which is much more convenient.

Promotion, But...

I posted this promotional post. Thankfully, it received a lot of attention and quickly made it to the HOT board.

But a problem arose.

After deploying that day's work, I was about to go to sleep while it was in review pending status. Then I realized I had uploaded the wrong version, so I rushed to cancel it.

I clicked the Unpublish button, but this wasn't for canceling the review -- it was for unpublishing the program from the store... lol

So my program was taken down from the store, and the store link in my promotional post started showing a 404 -- a very awkward situation.

I searched for a way to undo the cancellation, but there was no way. Even unpublishing required Google's review and approval. I had no idea when it would be approved, so all I could do was wait endlessly. I posted on the promotional thread asking for understanding while it was being restored.

Fortunately, it was approved the next evening, and I quickly re-uploaded it. (Ironically, the broken link might have led more people to bookmark the post.)

Promotion Results

Everytime

Chrome Store

Whale Store

I was surprised by how much interest people showed. The comments and active feedback through the feedback form were incredibly helpful.

Thanks to the feedback, I was able to fix some errors and learned about many useful features to add, which I plan to actively incorporate.

Just the Beginning

After promoting, I was startled by the flood of error logs in Sentry. That's when I truly realized the importance of testing, and I've been gradually writing test code since then.

It's not "deploy and done!" -- it feels like this is just the beginning. I want to keep improving and provide users with even better features going forward.

Reflections

Having developed and deployed my first extension like this, I'm grateful that many fellow students showed interest and used it, which gave me a lot of valuable experience.

This was my first time creating a service used by real users, which made this project one where I learned more than any other.

Having done a project as a Chrome extension, I realized there's so much you can do with it. I think building an extension for my next side project could be a great idea!