nccache/README.md

# Course Cache

(iykyk)


This guide explains how to install a browser extension directly from its source directory for development and testing.

This process is commonly referred to as **loading an unpacked extension**.

> [!WARNING]
> Only load unpacked extensions from code you trust. Development extensions bypass the normal browser extension-store installation process and may request powerful browser permissions. Chrome specifically recommends using unpacked extensions only for trusted code during development.

## Supported Browsers

The process is similar across most desktop Chromium-based browsers, including:

* Google Chrome
* Microsoft Edge
* Brave
* Opera
* Other Chromium-based browsers that expose the standard extensions management page

The examples below focus on desktop browsers.

---

Chrome and Edge both load development extensions by selecting the directory containing the extension's source files and manifest.

If you downloaded the extension as a ZIP file, extract it first.

For example:

```text
Downloads/
└── nccache/
    ├── src/
    └── ...
```

Do **not** select the ZIP file itself when using **Load unpacked**.

---

# Google Chrome

## 1. Open the Extensions Page

Enter the following into Chrome's address bar:

```text
chrome://extensions
```

Chrome also exposes the extensions manager through its Extensions menu.

## 2. Enable Developer Mode

Turn on:

```text
Developer mode
```

The toggle is normally located near the top of the Extensions page.

## 3. Load the Extension

Click:

```text
Load unpacked
```

Then select the directory containing:

```text
manifest.json
```

For example:

```text
~/Downloads/ncache/src/
```

Chrome will install the extension directly from that directory.

## 4. Verify the Extension

The extension should now appear on the Extensions page.

Depending on the extension, you may also see its icon in Chrome's Extensions menu.

You can pin it to the toolbar from the Extensions menu if needed.

---

# Microsoft Edge

## 1. Open the Extensions Page

Open:

```text
edge://extensions
```

Alternatively, use:

```text
Settings and more
→ Extensions
→ Manage extensions
```

Microsoft documents the same developer-mode sideloading workflow for Edge.

## 2. Enable Developer Mode

Turn on:

```text
Developer mode
```

## 3. Load the Extension

Click:

```text
Load unpacked
```

Select the directory containing the extension source files and:

```text
manifest.json
```

Microsoft Edge will load the extension for local testing.

---

# Brave

Open Brave and navigate to:

```text
Menu
→ More tools
→ Extensions
```

Brave exposes installed extension management through this page.

From the extensions page:

1. Enable **Developer mode**.
2. Click **Load unpacked**.
3. Select your extension directory.
4. Confirm that the extension appears in the installed extensions list.

The directory should be the folder containing:

```text
manifest.json
```

---

# Opera

## 1. Open the Extensions Page

Enter:

```text
opera://extensions/
```

Opera documentation also refers to this page as:

```text
opera:extensions
```

## 2. Enable Developer Mode

Enable:

```text
Developer Mode
```

## 3. Load the Extension

Choose:

```text
Load unpacked
```

or the equivalent **Load Extension** option shown by your Opera version.

Select the extension directory containing the manifest and other source files. Opera documents loading extensions directly from their directories for development and testing.

---

# Updating the Extension During Development

Loading an unpacked extension does **not** mean you have to reinstall it every time you change your code.

Edit your source normally:

```text
my-extension/
├── manifest.json
├── background.js
└── content.js
```

For example:

```bash
code my-extension/
```

After making changes, return to the browser's Extensions page.

Find your extension and click its:

```text
Reload
```

button or reload icon.

Chrome and Opera both expose a reload mechanism specifically for updating development extensions after source changes.

A typical workflow is therefore:

```text
Edit code
   ↓
Save files
   ↓
Open Extensions page
   ↓
Reload extension
   ↓
Refresh the webpage being tested
   ↓
Test changes
```

You may need to refresh any existing webpage where your extension's content scripts are running.

---

# Inspecting and Debugging the Extension

Development extensions can be debugged using the browser's Developer Tools.

## Popup

If the extension has a popup:

1. Open the extension popup.
2. Right-click inside it.
3. Choose **Inspect** or **Inspect element**.

This opens a dedicated DevTools window for the popup.

Opera, for example, explicitly supports inspecting extension popups through its developer tools.

## Web Page / Content Scripts

For code injected into a webpage:

```text
Right-click webpage
→ Inspect
```

Use the normal DevTools:

```text
Console
Sources
Network
Elements
```

to diagnose the extension.

## Background / Service Worker

For extensions using a background service worker, the Extensions page usually exposes an inspection link for the worker.

Look around the extension's development information for something similar to:

```text
Service worker
```

and select its inspection link.

---

# Common Problems

## "Manifest file is missing or unreadable"

Make sure you selected the correct directory.

Incorrect:

```text
my-extension/
└── extension/
    ├── manifest.json
    └── content.js
```

while selecting:

```text
my-extension/
```

Correct:

```text
my-extension/
└── extension/
    ├── manifest.json
    └── content.js
        ↑
        select this directory
```

The folder selected through **Load unpacked** should directly contain:

```text
manifest.json
```

---

## Extension Does Not Appear to Update

After changing the code:

1. Save your files.
2. Open the Extensions page.
3. Click **Reload** on the extension.
4. Refresh the webpage you are testing.

For Chrome:

```text
chrome://extensions
```

For Edge:

```text
edge://extensions
```

For Opera:

```text
opera://extensions/
```

---

## Extension Shows an Error

Open the Extensions page and inspect the error associated with the extension.

Common causes include:

```text
Invalid manifest.json
Missing files
Invalid permissions
JavaScript syntax errors
Incorrect file paths
Unsupported extension APIs
```

Start by validating that `manifest.json` contains valid JSON.

For example:

```json
{
  "manifest_version": 3,
  "name": "My Development Extension",
  "version": "1.0.0"
}
```

---

## Changes to Content Scripts Are Not Visible

Reloading the extension does not necessarily update code that was already injected into an existing page.

Use:

```text
Reload extension
→ Refresh target webpage
```

If you're debugging several tabs, refresh each affected tab.

---

# Removing the Development Extension

Open your browser's Extensions page:

```text
Chrome:  chrome://extensions
Edge:    edge://extensions
Opera:   opera://extensions/
```

Locate the development extension and choose:

```text
Remove
```

or:

```text
Uninstall
```

Removing the extension from the browser does **not** delete your local source directory.

---

# Quick Reference

| Browser | Extensions Page                | Installation                   |
| ------- | ------------------------------ | ------------------------------ |
| Chrome  | `chrome://extensions`          | Developer mode → Load unpacked |
| Edge    | `edge://extensions`            | Developer mode → Load unpacked |
| Brave   | Extensions / Manage Extensions | Developer mode → Load unpacked |
| Opera   | `opera://extensions/`          | Developer Mode → Load unpacked |

The general Chromium development workflow is:

```text
1. Obtain or build the extension source
2. Extract it if necessary
3. Confirm manifest.json exists
4. Open the browser's Extensions page
5. Enable Developer mode
6. Click Load unpacked
7. Select the extension directory
8. Test the extension
9. Reload it after source changes
```

---

# Security Notes

Development extensions should be treated similarly to locally running applications.

Before loading an unfamiliar extension:

* Review its `manifest.json`.
* Check requested permissions.
* Review background/service-worker scripts.
* Review content scripts.
* Check for unexpected network requests.
* Avoid loading extension code from unknown or untrusted sources.

In particular, pay attention to permissions such as:

```json
{
  "permissions": [
    "tabs",
    "cookies",
    "storage"
  ],
  "host_permissions": [
    "<all_urls>"
  ]
}
```

An extension with broad permissions may be able to interact with a significant amount of browser activity.

For normal development and testing, prefer loading the extension directly from a local source directory rather than installing unknown prebuilt packages.