mirror of
https://github.com/BetterSEQTA/BetterSEQTA-Plus.git
synced 2026-06-05 19:24:39 +00:00
docs: more comprehensive documentation
This commit is contained in:
SethBurkart123
+22
-4
@@ -1,13 +1,31 @@
|
|||||||
# Contributing
|
# Contributing to BetterSEQTA+
|
||||||
|
|
||||||
When contributing to this repository, please first discuss the change you wish to make via issue,
|
Hey there! 👋 Thanks for your interest in contributing to BetterSEQTA+! We're excited to have you join our community of contributors.
|
||||||
email, or any other method with the owners of this repository before making a change.
|
|
||||||
|
## 🚀 New Contributors Start Here!
|
||||||
|
|
||||||
|
**Never contributed to an open source project before?** No worries! We've made it super easy to get started:
|
||||||
|
|
||||||
|
- **📖 Read our [Getting Started Guide](./docs/GETTING_STARTED_CONTRIBUTING.md)** - This walks you through everything step-by-step, from setting up your development environment to making your first pull request.
|
||||||
|
- **🏗️ Understand the codebase** with our [Architecture Guide](./docs/ARCHITECTURE.md)
|
||||||
|
- **🔧 Having issues?** Check our [Troubleshooting Guide](./docs/TROUBLESHOOTING.md)
|
||||||
|
|
||||||
|
We have lots of [`good first issue`](https://github.com/BetterSEQTA/BetterSEQTA-plus/labels/good%20first%20issue) labels that are perfect for beginners!
|
||||||
|
|
||||||
|
## Discussion Before Contributing
|
||||||
|
|
||||||
|
For significant changes, please first discuss what you'd like to change via:
|
||||||
|
- Opening an issue
|
||||||
|
- Joining our Discord server
|
||||||
|
- Emailing the maintainers
|
||||||
|
|
||||||
|
This helps ensure your contribution aligns with the project's goals and saves you time!
|
||||||
|
|
||||||
## Community
|
## Community
|
||||||
|
|
||||||
Join our community channels to discuss the project, get help, and connect with other contributors:
|
Join our community channels to discuss the project, get help, and connect with other contributors:
|
||||||
|
|
||||||
- **Discord Server**: [Join our Discord](https://discord.gg/betterseqta)
|
- **Discord Server**: [Join our Discord](https://discord.gg/YzmbnCDkat)
|
||||||
- **GitHub Discussions**: For longer-form conversations
|
- **GitHub Discussions**: For longer-form conversations
|
||||||
- **GitHub Issues**: For bug reports and feature requests
|
- **GitHub Issues**: For bug reports and feature requests
|
||||||
|
|
||||||
|
|||||||
@@ -56,58 +56,46 @@ If you are looking to create custom themes, I would recommend you start at the o
|
|||||||
|
|
||||||
Don't worry- if you get stuck feel free to ask around in the [discord](https://discord.gg/YzmbnCDkat). We're open and happy to help out! Happy creating :)
|
Don't worry- if you get stuck feel free to ask around in the [discord](https://discord.gg/YzmbnCDkat). We're open and happy to help out! Happy creating :)
|
||||||
|
|
||||||
## Getting started
|
## 🚀 Want to Contribute?
|
||||||
|
|
||||||
**1. Clone the repository**
|
**New contributors welcome!** 🎉 We've made it easy to get started:
|
||||||
|
|
||||||
```
|
- **👋 New to the project?** Start with our [Getting Started Guide](./docs/GETTING_STARTED_CONTRIBUTING.md)
|
||||||
git clone https://github.com/BetterSEQTA/BetterSEQTA-Plus
|
- **🏗️ Want to understand the code?** Check out our [Architecture Guide](./docs/ARCHITECTURE.md)
|
||||||
|
- **🧩 Interested in plugins?** Read our [Plugin Development Guide](./docs/plugins/README.md)
|
||||||
|
- **🐛 Found a bug?** Open an [issue](https://github.com/BetterSEQTA/BetterSEQTA-plus/issues) or fix it yourself!
|
||||||
|
- **💬 Need help?** Join our [Discord community](https://discord.gg/YzmbnCDkat)
|
||||||
|
|
||||||
|
We have lots of [`good first issue`](https://github.com/BetterSEQTA/BetterSEQTA-plus/labels/good%20first%20issue) labels perfect for beginners!
|
||||||
|
|
||||||
|
## Quick Development Setup
|
||||||
|
|
||||||
|
**1. Fork & Clone**
|
||||||
|
```bash
|
||||||
|
git clone https://github.com/YOUR_USERNAME/BetterSEQTA-Plus
|
||||||
|
cd BetterSEQTA-Plus
|
||||||
```
|
```
|
||||||
|
|
||||||
**2. Install dependencies**
|
**2. Install & Run**
|
||||||
|
```bash
|
||||||
You may install the dependencies like below:
|
npm install --legacy-peer-deps
|
||||||
|
npm run dev
|
||||||
```
|
|
||||||
npm install # or your preferred package manager like pnpm or yarn
|
|
||||||
```
|
```
|
||||||
|
|
||||||
But it is recommended to do it like this:
|
**3. Load in Browser**
|
||||||
|
1. Go to `chrome://extensions`
|
||||||
|
2. Enable "Developer mode"
|
||||||
|
3. Click "Load unpacked" → Select `dist` folder
|
||||||
|
4. Visit a SEQTA page to see it work! 🎉
|
||||||
|
|
||||||
|
📚 **Need more details?** Check our [detailed setup guide](./docs/GETTING_STARTED_CONTRIBUTING.md#your-first-30-minutes)
|
||||||
|
|
||||||
|
### Building for Production
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run build # Build for all browsers
|
||||||
|
npm run zip # Package for distribution (requires 7-Zip)
|
||||||
```
|
```
|
||||||
npm install --legacy-peer-deps # Only NPM supported
|
|
||||||
```
|
|
||||||
|
|
||||||
### Running Development
|
|
||||||
|
|
||||||
**3. Run the dev script (it updates as you save files)**
|
|
||||||
|
|
||||||
```
|
|
||||||
npm run dev # or use your preferred package manager
|
|
||||||
```
|
|
||||||
|
|
||||||
### Building for production
|
|
||||||
|
|
||||||
**4. Run the build script**
|
|
||||||
|
|
||||||
```
|
|
||||||
npm run build # or use your preferred package manager
|
|
||||||
```
|
|
||||||
|
|
||||||
**4.1. Package it up (optional)**
|
|
||||||
|
|
||||||
```
|
|
||||||
npm run zip # This REQUIRES 7-Zip to be installed in order to work. You can also use your preferred package manager
|
|
||||||
```
|
|
||||||
|
|
||||||
**5. Load the extension into chrome**
|
|
||||||
|
|
||||||
- Go to `chrome://extensions`
|
|
||||||
- Enable developer mode
|
|
||||||
- Click `Load unpacked`
|
|
||||||
- Select the `dist` folder
|
|
||||||
|
|
||||||
Just remember, in order to update changes to the extension if you are running in developer mode, you need to click the refresh button on the extension in `chrome://extensions` whenever anything's changed.
|
|
||||||
|
|
||||||
## Folder Structure
|
## Folder Structure
|
||||||
|
|
||||||
|
|||||||
@@ -0,0 +1,235 @@
|
|||||||
|
# BetterSEQTA+ Architecture
|
||||||
|
|
||||||
|
Hey there! 👋 New to the codebase and feeling a bit lost? Don't worry - this guide will help you understand how everything fits together!
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
- [Overview](#overview)
|
||||||
|
- [High-Level Architecture](#high-level-architecture)
|
||||||
|
- [Core Components](#core-components)
|
||||||
|
- [Plugin System](#plugin-system)
|
||||||
|
- [File Structure Explained](#file-structure-explained)
|
||||||
|
- [Data Flow](#data-flow)
|
||||||
|
- [Browser Extension Basics](#browser-extension-basics)
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
BetterSEQTA+ is a browser extension that enhances SEQTA Learn by:
|
||||||
|
- Adding new features through a plugin system
|
||||||
|
- Providing customizable themes and UI improvements
|
||||||
|
- Offering better navigation and user experience
|
||||||
|
|
||||||
|
Think of it like this: **SEQTA Learn + BetterSEQTA+ = Enhanced SEQTA Experience**
|
||||||
|
|
||||||
|
## High-Level Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────────┐
|
||||||
|
│ BROWSER EXTENSION │
|
||||||
|
├─────────────────────────────────────────────────────────────┤
|
||||||
|
│ │
|
||||||
|
│ ┌─────────────────┐ ┌──────────────────┐ │
|
||||||
|
│ │ Background │ │ Content Script │ │
|
||||||
|
│ │ Script │ │ (SEQTA.ts) │ │
|
||||||
|
│ │ │ │ │ │
|
||||||
|
│ │ - Settings │◄───┤ - Page Detection│ │
|
||||||
|
│ │ - Storage │ │ - Plugin Loading│ │
|
||||||
|
│ │ - Updates │ │ - UI Injection │ │
|
||||||
|
│ └─────────────────┘ └──────────────────┘ │
|
||||||
|
│ │ │
|
||||||
|
│ ┌─────────▼─────────┐ │
|
||||||
|
│ │ Plugin System │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ ┌─────────────┐ │ │
|
||||||
|
│ │ │ Built-in │ │ │
|
||||||
|
│ │ │ Plugins │ │ │
|
||||||
|
│ │ │ │ │ │
|
||||||
|
│ │ │ - Themes │ │ │
|
||||||
|
│ │ │ - Search │ │ │
|
||||||
|
│ │ │ - Timetable │ │ │
|
||||||
|
│ │ │ - etc... │ │ │
|
||||||
|
│ │ └─────────────┘ │ │
|
||||||
|
│ └───────────────────┘ │
|
||||||
|
│ │ │
|
||||||
|
│ ┌─────────▼─────────┐ │
|
||||||
|
│ │ Settings UI │ │
|
||||||
|
│ │ (Svelte App) │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ - Plugin Config │ │
|
||||||
|
│ │ - Theme Creator │ │
|
||||||
|
│ │ - General Settings│ │
|
||||||
|
│ └───────────────────┘ │
|
||||||
|
└─────────────────────────────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
┌─────────▼─────────┐
|
||||||
|
│ SEQTA Learn │
|
||||||
|
│ Website │
|
||||||
|
└───────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
## Core Components
|
||||||
|
|
||||||
|
### 1. Entry Point (`src/SEQTA.ts`)
|
||||||
|
This is where it all begins! When you visit a SEQTA page:
|
||||||
|
1. Detects if you're on a SEQTA Learn page
|
||||||
|
2. Injects our CSS styles
|
||||||
|
3. Changes the favicon to BetterSEQTA+ icon
|
||||||
|
4. Loads settings from storage
|
||||||
|
5. Initializes the plugin system
|
||||||
|
|
||||||
|
### 2. Plugin System (`src/plugins/`)
|
||||||
|
The heart of BetterSEQTA+! This is what makes it extensible:
|
||||||
|
- **Plugin Manager**: Registers and manages all plugins
|
||||||
|
- **Built-in Plugins**: Pre-made plugins (themes, search, etc.)
|
||||||
|
- **Plugin API**: Provides plugins with tools to interact with SEQTA
|
||||||
|
|
||||||
|
### 3. Settings UI (`src/interface/`)
|
||||||
|
A Svelte application that lets users:
|
||||||
|
- Enable/disable plugins
|
||||||
|
- Configure plugin settings
|
||||||
|
- Create custom themes
|
||||||
|
- Browse the theme store
|
||||||
|
|
||||||
|
### 4. Background Script (`src/background.ts`)
|
||||||
|
Runs in the background and handles:
|
||||||
|
- Extension-wide settings storage
|
||||||
|
- Communication between different parts
|
||||||
|
- Update notifications
|
||||||
|
|
||||||
|
## Plugin System
|
||||||
|
|
||||||
|
Our plugin system is what makes BetterSEQTA+ so powerful. Here's how it works:
|
||||||
|
|
||||||
|
### Plugin Lifecycle
|
||||||
|
```
|
||||||
|
Plugin Registration → Settings Loading → Plugin Initialization → Running → Cleanup
|
||||||
|
```
|
||||||
|
|
||||||
|
### Built-in Plugins Overview
|
||||||
|
|
||||||
|
| Plugin | What it does | Files |
|
||||||
|
|--------|-------------|-------|
|
||||||
|
| **Themes** | Custom CSS themes and backgrounds | `src/plugins/built-in/themes/` |
|
||||||
|
| **Global Search** | Search across all SEQTA content | `src/plugins/built-in/globalSearch/` |
|
||||||
|
| **Timetable** | Enhanced timetable features | `src/plugins/built-in/timetable/` |
|
||||||
|
| **Profile Picture** | Custom profile pictures | `src/plugins/built-in/profilePicture/` |
|
||||||
|
| **Animated Background** | Moving background animations | `src/plugins/built-in/animatedBackground/` |
|
||||||
|
|
||||||
|
### Creating a Plugin
|
||||||
|
Every plugin follows this structure:
|
||||||
|
```typescript
|
||||||
|
const myPlugin: Plugin = {
|
||||||
|
id: "unique-plugin-id",
|
||||||
|
name: "Human Readable Name",
|
||||||
|
description: "What does this plugin do?",
|
||||||
|
version: "1.0.0",
|
||||||
|
settings: { /* user configurable options */ },
|
||||||
|
run: async (api) => {
|
||||||
|
// Your plugin code goes here!
|
||||||
|
}
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
## File Structure Explained
|
||||||
|
|
||||||
|
```
|
||||||
|
src/
|
||||||
|
├── SEQTA.ts # 🚀 Main entry point - start reading here!
|
||||||
|
├── background.ts # 🔧 Background script for extension
|
||||||
|
├── manifests/ # 📦 Browser extension manifests
|
||||||
|
├── plugins/ # 🧩 Plugin system (the magic happens here!)
|
||||||
|
│ ├── core/ # 🏗️ Plugin infrastructure
|
||||||
|
│ ├── built-in/ # 🎁 Pre-made plugins
|
||||||
|
│ └── index.ts # 📋 Plugin registration
|
||||||
|
├── interface/ # 🎨 Settings UI (Svelte app)
|
||||||
|
│ ├── pages/ # 📄 Settings pages
|
||||||
|
│ ├── components/ # 🧱 Reusable UI components
|
||||||
|
│ └── main.ts # 🏠 Settings app entry point
|
||||||
|
├── seqta/ # 🔗 SEQTA-specific utilities
|
||||||
|
│ ├── main.ts # 🎯 Core SEQTA modifications
|
||||||
|
│ ├── ui/ # 🎨 UI manipulation helpers
|
||||||
|
│ └── utils/ # 🛠️ Helper functions
|
||||||
|
└── css/ # 💄 Styles and themes
|
||||||
|
```
|
||||||
|
|
||||||
|
### Where to Start Reading?
|
||||||
|
1. **New to the project?** Start with `src/SEQTA.ts`
|
||||||
|
2. **Want to understand plugins?** Look at `src/plugins/core/types.ts`
|
||||||
|
3. **Want to see a simple plugin?** Check out `src/plugins/built-in/profilePicture/`
|
||||||
|
4. **Interested in the UI?** Explore `src/interface/main.ts`
|
||||||
|
|
||||||
|
## Data Flow
|
||||||
|
|
||||||
|
Here's how data flows through the system:
|
||||||
|
|
||||||
|
```
|
||||||
|
User visits SEQTA → SEQTA.ts detects page → Loads settings from storage
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
Plugin Manager initializes → Each plugin gets API access → Plugins modify SEQTA
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
User opens settings → Svelte UI loads → Settings changed → Storage updated
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
Storage change detected → Plugins notified → UI updates automatically
|
||||||
|
```
|
||||||
|
|
||||||
|
## Browser Extension Basics
|
||||||
|
|
||||||
|
Never worked on a browser extension before? Here's what you need to know:
|
||||||
|
|
||||||
|
### Content Scripts vs Background Scripts
|
||||||
|
- **Content Script** (`SEQTA.ts`): Runs on SEQTA pages, can access and modify the page
|
||||||
|
- **Background Script** (`background.ts`): Runs in the background, handles storage and messaging
|
||||||
|
|
||||||
|
### Manifest Files
|
||||||
|
Each browser needs a slightly different manifest file:
|
||||||
|
- `manifests/chrome.ts` - Chrome, Edge, Brave
|
||||||
|
- `manifests/firefox.ts` - Firefox
|
||||||
|
- `manifests/safari.ts` - Safari (experimental)
|
||||||
|
|
||||||
|
### Communication
|
||||||
|
Different parts of the extension communicate using:
|
||||||
|
- `browser.runtime.sendMessage()` - Send messages
|
||||||
|
- `browser.storage` - Shared storage, but we have created a custom storage system that is easier to use:
|
||||||
|
```ts
|
||||||
|
settingsState.[the setting name] = [whatever you want to set it to]
|
||||||
|
console.log(settingsState.[the setting name])
|
||||||
|
```
|
||||||
|
- Custom events for plugin communication
|
||||||
|
|
||||||
|
## Development Tips
|
||||||
|
|
||||||
|
### Debugging
|
||||||
|
1. **Chrome DevTools**: Right-click → Inspect → Console tab
|
||||||
|
2. **Extension Console**: `chrome://extensions` → BetterSEQTA+ → "Inspect views: background page"
|
||||||
|
3. **Look for logs**: We log everything with `[BetterSEQTA+]` prefix
|
||||||
|
|
||||||
|
### Making Changes
|
||||||
|
1. Edit code → Save → Browser auto-reloads extension → Refresh SEQTA page
|
||||||
|
2. For UI changes: The dev server hot-reloads automatically
|
||||||
|
3. For plugin changes: May need to disable/enable the plugin in settings
|
||||||
|
|
||||||
|
### Common Gotchas
|
||||||
|
- Settings take a moment to load (use `api.settings.loaded` promise)
|
||||||
|
- Some SEQTA elements load dynamically (use `api.seqta.onMount()`)
|
||||||
|
- Plugin cleanup is important (always return a cleanup function)
|
||||||
|
|
||||||
|
## Next Steps
|
||||||
|
|
||||||
|
Ready to contribute? Here's what to do next:
|
||||||
|
|
||||||
|
1. **Read the code**: Start with `src/SEQTA.ts` and follow the flow
|
||||||
|
2. **Try creating a simple plugin**: Follow our [plugin guide](./plugins/README.md)
|
||||||
|
3. **Look at existing issues**: Check our [GitHub issues](https://github.com/BetterSEQTA/BetterSEQTA-plus/issues) for "good first issue" labels
|
||||||
|
4. **Join our Discord**: Get help from the community!
|
||||||
|
|
||||||
|
## Questions?
|
||||||
|
|
||||||
|
Still confused about something? That's totally normal! Here are your options:
|
||||||
|
- 💬 Ask in our [Discord server](https://discord.gg/YzmbnCDkat)
|
||||||
|
- 🐛 Open an issue on GitHub
|
||||||
|
- 📧 Email us at betterseqta@betterseqta.com
|
||||||
|
|
||||||
|
Remember: **Every expert was once a beginner!** We're here to help you learn and contribute. 🚀
|
||||||
@@ -0,0 +1,285 @@
|
|||||||
|
# Getting Started as a Contributor
|
||||||
|
|
||||||
|
Welcome to BetterSEQTA+! 🎉 This guide will walk you through making your first contribution, even if you're completely new to the project.
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
- [Before You Start](#before-you-start)
|
||||||
|
- [Your First 30 Minutes](#your-first-30-minutes)
|
||||||
|
- [Making Your First Contribution](#making-your-first-contribution)
|
||||||
|
- [Types of Contributions](#types-of-contributions)
|
||||||
|
- [Finding Something to Work On](#finding-something-to-work-on)
|
||||||
|
- [Development Workflow](#development-workflow)
|
||||||
|
- [Getting Help](#getting-help)
|
||||||
|
|
||||||
|
## Before You Start
|
||||||
|
|
||||||
|
### What You'll Need
|
||||||
|
- **Node.js** (v16 or higher) - [Download here](https://nodejs.org/)
|
||||||
|
- **Git** - [Download here](https://git-scm.com/)
|
||||||
|
- **A code editor** - We recommend [VS Code](https://code.visualstudio.com/)
|
||||||
|
- **A Chromium browser** (Chrome, Edge, Brave) for testing (recommended, however you can use firefox although it requires being built every time you make a change)
|
||||||
|
|
||||||
|
### Helpful Background (but not required!)
|
||||||
|
- Basic JavaScript/TypeScript knowledge
|
||||||
|
- Some familiarity with HTML/CSS
|
||||||
|
- Understanding of browser extensions (we'll teach you!)
|
||||||
|
|
||||||
|
**Don't worry if you're missing some of these!** We're happy to help you learn. 🤗
|
||||||
|
|
||||||
|
## Your First 30 Minutes
|
||||||
|
|
||||||
|
Let's get you up and running quickly:
|
||||||
|
|
||||||
|
### 1. Get the Code (3 minutes)
|
||||||
|
```bash
|
||||||
|
# Fork the repository on GitHub first, then:
|
||||||
|
git clone https://github.com/YOUR_USERNAME/BetterSEQTA-plus.git
|
||||||
|
cd BetterSEQTA-plus
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Install Dependencies (3 minutes)
|
||||||
|
```bash
|
||||||
|
npm install --legacy-peer-deps
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Start Development Server (2 minutes)
|
||||||
|
```bash
|
||||||
|
npm run dev
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Load Extension in Browser (4 minutes)
|
||||||
|
1. Open Chrome and go to `chrome://extensions`
|
||||||
|
2. Enable "Developer mode" (toggle in top right)
|
||||||
|
3. Click "Load unpacked"
|
||||||
|
4. Select the `dist` folder in your project
|
||||||
|
5. Visit a SEQTA Learn page to see BetterSEQTA+ in action!
|
||||||
|
|
||||||
|
### 5. Make a Tiny Change (5 minutes)
|
||||||
|
Let's prove everything works:
|
||||||
|
1. Open `src/SEQTA.ts`
|
||||||
|
2. Find the line that says `"[BetterSEQTA+] Successfully initialised"`
|
||||||
|
3. Change it to `"[BetterSEQTA+] Successfully initialised - Hello [YOUR_NAME]!"`
|
||||||
|
4. Save the file
|
||||||
|
5. Go to `chrome://extensions`, click the refresh icon on BetterSEQTA+
|
||||||
|
6. Refresh a SEQTA page and check the browser console (F12) - you should see your message!
|
||||||
|
|
||||||
|
### 6. Reset Your Change (3 minutes)
|
||||||
|
```bash
|
||||||
|
git checkout -- src/SEQTA.ts
|
||||||
|
```
|
||||||
|
|
||||||
|
**Congratulations! 🎉 You've successfully set up BetterSEQTA+ for development!**
|
||||||
|
|
||||||
|
## Making Your First Contribution
|
||||||
|
|
||||||
|
### Easy First Contributions
|
||||||
|
|
||||||
|
Here are some great starter contributions:
|
||||||
|
|
||||||
|
1. **Fix a typo in documentation** - Super easy and always appreciated!
|
||||||
|
2. **Improve error messages** - Make them more helpful
|
||||||
|
3. **Add comments to code** - Help other contributors understand
|
||||||
|
4. **Create a simple plugin** - Follow our plugin guide
|
||||||
|
5. **Fix a bug you found** - If you found a bug, fix it!
|
||||||
|
|
||||||
|
### Step-by-Step: Your First Pull Request
|
||||||
|
|
||||||
|
#### Step 1: Pick an Issue
|
||||||
|
- Go to our [Issues page](https://github.com/BetterSEQTA/BetterSEQTA-plus/issues)
|
||||||
|
- Look for labels like:
|
||||||
|
- `good first issue` - Perfect for beginners
|
||||||
|
- `help wanted` - We'd love help with these
|
||||||
|
- `documentation` - Improve our docs
|
||||||
|
- `bug` - Fix something broken
|
||||||
|
|
||||||
|
#### Step 2: Claim the Issue
|
||||||
|
Comment on the issue saying "I'd like to work on this!" We'll assign it to you.
|
||||||
|
|
||||||
|
#### Step 3: Create a Branch
|
||||||
|
```bash
|
||||||
|
git checkout -b fix-issue-123 # Replace 123 with the issue number
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Step 4: Make Your Changes
|
||||||
|
- Follow the patterns you see in existing code
|
||||||
|
- Test your changes thoroughly
|
||||||
|
- Keep changes focused and small
|
||||||
|
|
||||||
|
#### Step 5: Test Everything
|
||||||
|
```bash
|
||||||
|
# Test the extension still loads
|
||||||
|
npm run dev
|
||||||
|
|
||||||
|
# Test in browser
|
||||||
|
# 1. Reload extension at chrome://extensions
|
||||||
|
# 2. Visit SEQTA page
|
||||||
|
# 3. Verify everything still works
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Step 6: Commit Your Changes
|
||||||
|
```bash
|
||||||
|
git add .
|
||||||
|
git commit -m "Fix issue #123: Brief description of what you fixed"
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Step 7: Push and Create Pull Request
|
||||||
|
```bash
|
||||||
|
git push origin fix-issue-123
|
||||||
|
```
|
||||||
|
|
||||||
|
Then go to GitHub and create a pull request with:
|
||||||
|
- **Clear title**: "Fix issue #123: Brief description"
|
||||||
|
- **Description**: Explain what you changed and why
|
||||||
|
- **Testing**: Describe how you tested it
|
||||||
|
|
||||||
|
## Types of Contributions
|
||||||
|
|
||||||
|
### 🐛 Bug Fixes
|
||||||
|
- Fix broken features
|
||||||
|
- Improve error handling
|
||||||
|
- Resolve compatibility issues
|
||||||
|
|
||||||
|
**Example**: "The theme selector doesn't work on Firefox"
|
||||||
|
|
||||||
|
### ✨ New Features
|
||||||
|
- Add new plugins
|
||||||
|
- Enhance existing functionality
|
||||||
|
- Improve user experience
|
||||||
|
|
||||||
|
**Example**: "Add keyboard shortcuts for common actions"
|
||||||
|
|
||||||
|
### 📚 Documentation
|
||||||
|
- Fix typos and unclear explanations
|
||||||
|
- Add examples and tutorials
|
||||||
|
- Improve code comments
|
||||||
|
|
||||||
|
**Example**: "Add more examples to the plugin guide"
|
||||||
|
|
||||||
|
### 🎨 Design & UI
|
||||||
|
- Improve the settings interface
|
||||||
|
- Make things more user-friendly
|
||||||
|
- Add animations and polish
|
||||||
|
|
||||||
|
**Example**: "Make the theme creator more intuitive"
|
||||||
|
|
||||||
|
### 🔧 Technical Improvements
|
||||||
|
- Refactor code for clarity
|
||||||
|
- Add tests
|
||||||
|
- Improve performance
|
||||||
|
|
||||||
|
**Example**: "Simplify the plugin loading logic"
|
||||||
|
|
||||||
|
## Finding Something to Work On
|
||||||
|
|
||||||
|
### Browse Issues by Label
|
||||||
|
- [`good first issue`](https://github.com/BetterSEQTA/BetterSEQTA-plus/labels/good%20first%20issue) - Perfect for beginners
|
||||||
|
- [`help wanted`](https://github.com/BetterSEQTA/BetterSEQTA-plus/labels/help%20wanted) - We need help with these
|
||||||
|
- [`documentation`](https://github.com/BetterSEQTA/BetterSEQTA-plus/labels/documentation) - Improve our docs
|
||||||
|
- [`bug`](https://github.com/BetterSEQTA/BetterSEQTA-plus/labels/bug) - Fix something broken
|
||||||
|
- [`enhancement`](https://github.com/BetterSEQTA/BetterSEQTA-plus/labels/enhancement) - Add new features
|
||||||
|
|
||||||
|
### Create Your Own Issue
|
||||||
|
Found a bug or have an idea? Create an issue first to discuss it!
|
||||||
|
|
||||||
|
### Plugin Ideas
|
||||||
|
Want to create a plugin? Here are some ideas:
|
||||||
|
- **Study Timer**: Track study time across SEQTA pages
|
||||||
|
- **Grade Tracker**: Better visualization of grades over time
|
||||||
|
- **Quick Notes**: Add notes to any SEQTA page
|
||||||
|
- **Homework Reminder**: Smart notifications for upcoming due dates
|
||||||
|
- **Custom Shortcuts**: User-defined keyboard shortcuts
|
||||||
|
|
||||||
|
## Development Workflow
|
||||||
|
|
||||||
|
### Daily Development
|
||||||
|
```bash
|
||||||
|
# Start working
|
||||||
|
git pull origin main
|
||||||
|
npm run dev
|
||||||
|
|
||||||
|
# Make changes, test, commit
|
||||||
|
git add .
|
||||||
|
git commit -m "Descriptive commit message"
|
||||||
|
|
||||||
|
# Push when ready
|
||||||
|
git push origin your-branch-name
|
||||||
|
```
|
||||||
|
|
||||||
|
### Before Submitting PR
|
||||||
|
1. **Test thoroughly** - Make sure nothing breaks
|
||||||
|
2. **Check console** - No new errors
|
||||||
|
3. **Test in different browsers** - Chrome and Firefox
|
||||||
|
4. **Update documentation** - If you changed how something works
|
||||||
|
|
||||||
|
### Code Style
|
||||||
|
- Use TypeScript where possible
|
||||||
|
- Follow existing naming conventions
|
||||||
|
- Add comments for complex logic
|
||||||
|
- Keep functions small and focused
|
||||||
|
|
||||||
|
## Getting Help
|
||||||
|
|
||||||
|
### Stuck? Here's How to Get Unstuck
|
||||||
|
|
||||||
|
1. **Check the docs** - [Architecture guide](./ARCHITECTURE.md) explains everything
|
||||||
|
2. **Search existing issues** - Someone might have had the same problem
|
||||||
|
3. **Ask in Discord** - Our community is super helpful
|
||||||
|
4. **Create an issue** - If you found a bug or need help
|
||||||
|
|
||||||
|
### Discord Community
|
||||||
|
Join our [Discord server](https://discord.gg/YzmbnCDkat) for:
|
||||||
|
- Real-time help and discussion
|
||||||
|
- Collaboration on features
|
||||||
|
- Sharing ideas and feedback
|
||||||
|
- Getting to know the community
|
||||||
|
|
||||||
|
### Code Review Process
|
||||||
|
- All contributions need code review
|
||||||
|
- We'll provide helpful feedback
|
||||||
|
- Don't worry about making mistakes - we're here to help!
|
||||||
|
- Reviews usually happen within 24-48 hours
|
||||||
|
|
||||||
|
## Common Questions
|
||||||
|
|
||||||
|
**Q: I'm new to browser extensions. Is this too advanced for me?**
|
||||||
|
A: Not at all! We have lots of beginner-friendly issues, and our plugin system makes it easy to add features without understanding all the browser extension complexities.
|
||||||
|
|
||||||
|
**Q: How long does it take to get my first PR merged?**
|
||||||
|
A: For simple fixes, usually 1-3 days. For larger features, it might take a week or two as we discuss the best approach.
|
||||||
|
|
||||||
|
**Q: I made a mistake in my PR. What do I do?**
|
||||||
|
A: No worries! Just push more commits to the same branch and they'll be added to your PR automatically.
|
||||||
|
|
||||||
|
**Q: Can I work on multiple issues at once?**
|
||||||
|
A: It's better to focus on one issue at a time, especially when starting out. This makes code review easier and reduces conflicts.
|
||||||
|
|
||||||
|
**Q: What if I start working on something and get stuck?**
|
||||||
|
A: Ask for help! Create a draft PR with what you have so far, and we'll help you figure out the next steps.
|
||||||
|
|
||||||
|
## Recognition
|
||||||
|
|
||||||
|
All contributors get:
|
||||||
|
- Recognition in our README
|
||||||
|
- Contributor badge in Discord
|
||||||
|
- Our eternal gratitude! 🙏
|
||||||
|
|
||||||
|
Significant contributors may also get:
|
||||||
|
- Special Discord roles
|
||||||
|
- Input on project direction
|
||||||
|
- Maintainer status
|
||||||
|
|
||||||
|
## Next Steps
|
||||||
|
|
||||||
|
Ready to contribute? Here's what to do:
|
||||||
|
|
||||||
|
1. ✅ **Set up your development environment** (follow the 30-minute guide above)
|
||||||
|
2. 🔍 **Find an issue to work on** (check the "good first issue" label)
|
||||||
|
3. 💬 **Join our Discord** and introduce yourself
|
||||||
|
4. 🚀 **Make your first contribution** and submit a PR
|
||||||
|
|
||||||
|
Remember: **Every expert was once a beginner!** We're excited to help you learn and grow as a contributor. Welcome to the team! 🎉
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Questions? Suggestions for improving this guide? Open an issue or message us on Discord!*
|
||||||
+4
-1
@@ -10,7 +10,10 @@ Welcome to the BetterSEQTA+ documentation! This documentation will help you unde
|
|||||||
|
|
||||||
- [Project Overview](./README.md) - This file
|
- [Project Overview](./README.md) - This file
|
||||||
- [Installation Guide](./installation.md) - How to install and set up BetterSEQTA+
|
- [Installation Guide](./installation.md) - How to install and set up BetterSEQTA+
|
||||||
- [Contributing Guide](../CONTRIBUTING.md) - How to contribute to BetterSEQTA+
|
- [Getting Started Contributing](./GETTING_STARTED_CONTRIBUTING.md) - **Start here!** Complete beginner-friendly guide
|
||||||
|
- [Architecture Guide](./ARCHITECTURE.md) - How BetterSEQTA+ works under the hood
|
||||||
|
- [Contributing Guide](../CONTRIBUTING.md) - Official contribution guidelines
|
||||||
|
- [Troubleshooting](./TROUBLESHOOTING.md) - Common issues and solutions
|
||||||
|
|
||||||
### Plugin System
|
### Plugin System
|
||||||
|
|
||||||
|
|||||||
@@ -0,0 +1,348 @@
|
|||||||
|
# Troubleshooting Guide
|
||||||
|
|
||||||
|
Having issues with BetterSEQTA+ development? This guide covers the most common problems and their solutions.
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
- [Installation Issues](#installation-issues)
|
||||||
|
- [Development Server Issues](#development-server-issues)
|
||||||
|
- [Browser Extension Issues](#browser-extension-issues)
|
||||||
|
- [Plugin Development Issues](#plugin-development-issues)
|
||||||
|
- [Build Issues](#build-issues)
|
||||||
|
- [Still Stuck?](#still-stuck)
|
||||||
|
|
||||||
|
## Installation Issues
|
||||||
|
|
||||||
|
### ❌ "npm install" fails with peer dependency errors
|
||||||
|
|
||||||
|
**Problem**: You see errors about peer dependencies or conflicting packages.
|
||||||
|
|
||||||
|
**Solution**:
|
||||||
|
```bash
|
||||||
|
rm -rf node_modules package-lock.json
|
||||||
|
npm install --legacy-peer-deps
|
||||||
|
```
|
||||||
|
|
||||||
|
### ❌ "Cannot find module" errors
|
||||||
|
|
||||||
|
**Problem**: Node.js can't find required packages.
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
1. **Clear and reinstall**:
|
||||||
|
```bash
|
||||||
|
rm -rf node_modules
|
||||||
|
npm install --legacy-peer-deps
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Check Node.js version**:
|
||||||
|
```bash
|
||||||
|
node --version # Should be v16 or higher
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Try with npm cache clean**:
|
||||||
|
```bash
|
||||||
|
npm cache clean --force
|
||||||
|
npm install --legacy-peer-deps
|
||||||
|
```
|
||||||
|
|
||||||
|
### ❌ Permission errors on macOS/Linux
|
||||||
|
|
||||||
|
**Problem**: "EACCES" or permission denied errors.
|
||||||
|
|
||||||
|
**Solution**:
|
||||||
|
```bash
|
||||||
|
sudo chown -R $(whoami) ~/.npm
|
||||||
|
sudo chown -R $(whoami) /usr/local/lib/node_modules
|
||||||
|
```
|
||||||
|
|
||||||
|
## Development Server Issues
|
||||||
|
|
||||||
|
### ❌ "npm run dev" fails
|
||||||
|
|
||||||
|
**Problem**: Development server won't start.
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
1. **Check if port is in use**:
|
||||||
|
```bash
|
||||||
|
lsof -i :5173 # Kill the process using the port
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Clear dist folder**:
|
||||||
|
```bash
|
||||||
|
rm -rf dist
|
||||||
|
npm run dev
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Check for TypeScript errors**:
|
||||||
|
```bash
|
||||||
|
npx tsc --noEmit # Check for type errors
|
||||||
|
```
|
||||||
|
|
||||||
|
### ❌ Changes not reflecting in browser
|
||||||
|
|
||||||
|
**Problem**: You make code changes but don't see them in the browser.
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
1. **Reload the extension**:
|
||||||
|
- Go to `chrome://extensions`
|
||||||
|
- Find BetterSEQTA+ and click the refresh icon
|
||||||
|
- Refresh your SEQTA page
|
||||||
|
|
||||||
|
2. **Check if dev server is running**:
|
||||||
|
- Look for "Build completed" in your terminal
|
||||||
|
- If not, restart `npm run dev`
|
||||||
|
|
||||||
|
3. **Hard refresh the page**:
|
||||||
|
- Press `Ctrl+Shift+R` (or `Cmd+Shift+R` on Mac)
|
||||||
|
|
||||||
|
## Browser Extension Issues
|
||||||
|
|
||||||
|
### ❌ Extension doesn't load in Chrome
|
||||||
|
|
||||||
|
**Problem**: Extension appears in `chrome://extensions` but doesn't work.
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
1. **Check for errors**:
|
||||||
|
- Go to `chrome://extensions`
|
||||||
|
- Click "Errors" button on BetterSEQTA+
|
||||||
|
- Fix any JavaScript errors shown
|
||||||
|
|
||||||
|
2. **Verify manifest**:
|
||||||
|
- Check if `dist/manifest.json` exists
|
||||||
|
- Ensure it has proper structure
|
||||||
|
|
||||||
|
3. **Check permissions**:
|
||||||
|
- Extension needs permission to access SEQTA pages
|
||||||
|
- Click "Details" → "Site access" → "On all sites"
|
||||||
|
|
||||||
|
### ❌ Extension doesn't appear on SEQTA pages
|
||||||
|
|
||||||
|
**Problem**: Extension loads but doesn't modify SEQTA.
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
1. **Check if you're on a SEQTA Learn page**:
|
||||||
|
- URL should contain "seqta" or "learn"
|
||||||
|
- Page title should include "SEQTA Learn"
|
||||||
|
|
||||||
|
2. **Check browser console**:
|
||||||
|
- Press `F12` → Console tab
|
||||||
|
- Look for "[BetterSEQTA+]" messages
|
||||||
|
- If no messages, extension isn't running
|
||||||
|
|
||||||
|
3. **Verify page detection**:
|
||||||
|
- Extension only runs on actual SEQTA Learn pages
|
||||||
|
- Test on a real SEQTA instance
|
||||||
|
|
||||||
|
### ❌ Settings page won't open
|
||||||
|
|
||||||
|
**Problem**: Clicking the extension icon doesn't open settings.
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
1. **Check popup errors**:
|
||||||
|
- Right-click extension icon → "Inspect popup"
|
||||||
|
- Look for JavaScript errors
|
||||||
|
|
||||||
|
2. **Clear extension storage**:
|
||||||
|
```javascript
|
||||||
|
// In browser console on any page:
|
||||||
|
chrome.storage.local.clear()
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Reload extension and try again**
|
||||||
|
|
||||||
|
## Plugin Development Issues
|
||||||
|
|
||||||
|
### ❌ My plugin doesn't appear in settings
|
||||||
|
|
||||||
|
**Problem**: Created a plugin but it's not showing up.
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
1. **Check plugin registration**:
|
||||||
|
- Ensure your plugin is imported in `src/plugins/index.ts`
|
||||||
|
- Verify `pluginManager.registerPlugin(yourPlugin)` is called
|
||||||
|
|
||||||
|
2. **Check plugin structure**:
|
||||||
|
```typescript
|
||||||
|
// Ensure your plugin has all required fields
|
||||||
|
const myPlugin: Plugin = {
|
||||||
|
id: "unique-id", // Must be unique
|
||||||
|
name: "Display Name",
|
||||||
|
description: "What it does",
|
||||||
|
version: "1.0.0",
|
||||||
|
run: async (api) => {
|
||||||
|
// Your code here
|
||||||
|
}
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Check for errors**:
|
||||||
|
- Look in browser console for plugin loading errors
|
||||||
|
|
||||||
|
### ❌ Plugin settings not working
|
||||||
|
|
||||||
|
**Problem**: Plugin settings don't save or load properly.
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
1. **Check settings definition**:
|
||||||
|
```typescript
|
||||||
|
import { defineSettings, booleanSetting } from "@/plugins/core/settingsHelpers";
|
||||||
|
|
||||||
|
const settings = defineSettings({
|
||||||
|
myOption: booleanSetting({
|
||||||
|
default: true,
|
||||||
|
title: "My Option",
|
||||||
|
description: "What this does"
|
||||||
|
})
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Wait for settings to load**:
|
||||||
|
```typescript
|
||||||
|
run: async (api) => {
|
||||||
|
await api.settings.loaded; // Wait for settings to load
|
||||||
|
console.log(api.settings.myOption); // Now you can use settings
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### ❌ Plugin API functions not working
|
||||||
|
|
||||||
|
**Problem**: `api.seqta.onMount()` or other API functions don't work.
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
1. **Check selector specificity**:
|
||||||
|
```typescript
|
||||||
|
// Be specific with selectors
|
||||||
|
api.seqta.onMount(".home-page", (element) => {
|
||||||
|
// Your code
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Wait for elements**:
|
||||||
|
```typescript
|
||||||
|
// Some elements load after page navigation
|
||||||
|
api.seqta.onPageChange((page) => {
|
||||||
|
if (page === "home") {
|
||||||
|
api.seqta.onMount(".home-content", (element) => {
|
||||||
|
// Now element should exist
|
||||||
|
});
|
||||||
|
}
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## Build Issues
|
||||||
|
|
||||||
|
### ❌ "npm run build" fails
|
||||||
|
|
||||||
|
**Problem**: Production build fails with errors.
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
1. **Check TypeScript errors**:
|
||||||
|
```bash
|
||||||
|
npx tsc --noEmit
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Clear cache and rebuild**:
|
||||||
|
```bash
|
||||||
|
rm -rf dist node_modules
|
||||||
|
npm install --legacy-peer-deps
|
||||||
|
npm run build
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Check for import errors**:
|
||||||
|
- Ensure all imports use correct paths
|
||||||
|
- Check for missing files
|
||||||
|
|
||||||
|
### ❌ Built extension doesn't work
|
||||||
|
|
||||||
|
**Problem**: `npm run build` succeeds but extension doesn't work.
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
1. **Test the built extension**:
|
||||||
|
- Load the `dist` folder as unpacked extension
|
||||||
|
- Check console for errors
|
||||||
|
|
||||||
|
2. **Compare with dev version**:
|
||||||
|
- If dev works but build doesn't, there might be a build configuration issue
|
||||||
|
|
||||||
|
3. **Check manifest generation**:
|
||||||
|
- Verify `dist/manifest.json` looks correct
|
||||||
|
- Compare with working version
|
||||||
|
|
||||||
|
## Common Error Messages
|
||||||
|
|
||||||
|
### "Cannot access contents of the URL"
|
||||||
|
- **Cause**: Extension permissions issue
|
||||||
|
- **Fix**: Go to `chrome://extensions` → BetterSEQTA+ → Details → Site access → "On all sites"
|
||||||
|
|
||||||
|
### "Extension context invalidated"
|
||||||
|
- **Cause**: Extension was reloaded while page was open
|
||||||
|
- **Fix**: Refresh the SEQTA page
|
||||||
|
|
||||||
|
### "Uncaught ReferenceError: browser is not defined"
|
||||||
|
- **Cause**: Missing webextension-polyfill import
|
||||||
|
- **Fix**: Add `import browser from "webextension-polyfill";` at top of file
|
||||||
|
|
||||||
|
### "Module not found: Can't resolve '@/...' "
|
||||||
|
- **Cause**: TypeScript path mapping issue
|
||||||
|
- **Fix**: Check `tsconfig.json` and `vite.config.ts` for path configuration
|
||||||
|
|
||||||
|
## Performance Issues
|
||||||
|
|
||||||
|
### Extension makes SEQTA slow
|
||||||
|
1. **Check for memory leaks**:
|
||||||
|
- Use Chrome DevTools → Performance tab
|
||||||
|
- Look for growing memory usage
|
||||||
|
|
||||||
|
2. **Optimize plugin code**:
|
||||||
|
- Remove unnecessary listeners
|
||||||
|
- Clean up intervals/timeouts
|
||||||
|
- Use efficient selectors
|
||||||
|
|
||||||
|
3. **Profile your changes**:
|
||||||
|
- Test with extension disabled vs enabled
|
||||||
|
- Identify which plugin is causing issues
|
||||||
|
|
||||||
|
## Still Stuck?
|
||||||
|
|
||||||
|
If none of these solutions work:
|
||||||
|
|
||||||
|
1. **🔍 Search existing issues**: [GitHub Issues](https://github.com/BetterSEQTA/BetterSEQTA-plus/issues)
|
||||||
|
|
||||||
|
2. **💬 Ask on Discord**: [Join our server](https://discord.gg/YzmbnCDkat) - fastest way to get help!
|
||||||
|
|
||||||
|
3. **📝 Create a new issue**: Include:
|
||||||
|
- Your operating system
|
||||||
|
- Node.js version (`node --version`)
|
||||||
|
- Browser version
|
||||||
|
- Exact error message
|
||||||
|
- Steps to reproduce
|
||||||
|
- What you've already tried
|
||||||
|
|
||||||
|
4. **📧 Email us**: betterseqta@betterseqta.com for urgent issues
|
||||||
|
|
||||||
|
## Getting More Debug Info
|
||||||
|
|
||||||
|
### Enable verbose logging
|
||||||
|
Add this to your plugin's `run` function:
|
||||||
|
```typescript
|
||||||
|
console.log("[DEBUG] Plugin starting:", api);
|
||||||
|
```
|
||||||
|
|
||||||
|
### Check extension background page
|
||||||
|
1. Go to `chrome://extensions`
|
||||||
|
2. Click "Details" on BetterSEQTA+
|
||||||
|
3. Click "Inspect views: background page"
|
||||||
|
4. Check console for background script errors
|
||||||
|
|
||||||
|
### Export debug info
|
||||||
|
Run this in browser console on a SEQTA page:
|
||||||
|
```javascript
|
||||||
|
console.log("Extension info:", {
|
||||||
|
version: chrome.runtime.getManifest().version,
|
||||||
|
url: window.location.href,
|
||||||
|
userAgent: navigator.userAgent,
|
||||||
|
storage: await chrome.storage.local.get()
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
Remember: **Don't give up!** Every developer faces these issues. The community is here to help, and solving these problems makes you a better developer. 💪
|
||||||
@@ -0,0 +1,335 @@
|
|||||||
|
# Example Plugin Template
|
||||||
|
|
||||||
|
This is a complete, working example of a simple BetterSEQTA+ plugin. You can copy this code and modify it to create your own plugin!
|
||||||
|
|
||||||
|
## What This Example Does
|
||||||
|
|
||||||
|
This plugin adds a friendly welcome message to the SEQTA homepage and lets users customize the message through settings.
|
||||||
|
|
||||||
|
## Complete Plugin Code
|
||||||
|
|
||||||
|
Create a new file in `src/plugins/built-in/my-first-plugin/index.ts`:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import type { Plugin } from "@/plugins/core/types";
|
||||||
|
import { BasePlugin } from "@/plugins/core/settings";
|
||||||
|
import {
|
||||||
|
defineSettings,
|
||||||
|
booleanSetting,
|
||||||
|
stringSetting
|
||||||
|
} from "@/plugins/core/settingsHelpers";
|
||||||
|
import { Setting } from "@/plugins/core/settingsHelpers";
|
||||||
|
|
||||||
|
// Define the plugin settings
|
||||||
|
const settings = defineSettings({
|
||||||
|
enabled: booleanSetting({
|
||||||
|
default: true,
|
||||||
|
title: "Show Welcome Message",
|
||||||
|
description: "Display a welcome message on the SEQTA homepage"
|
||||||
|
}),
|
||||||
|
customMessage: stringSetting({
|
||||||
|
default: "Welcome to SEQTA! 🎉",
|
||||||
|
title: "Custom Message",
|
||||||
|
description: "The message to display on the homepage",
|
||||||
|
maxLength: 100
|
||||||
|
}),
|
||||||
|
showEmoji: booleanSetting({
|
||||||
|
default: true,
|
||||||
|
title: "Show Emoji",
|
||||||
|
description: "Include emojis in the welcome message"
|
||||||
|
})
|
||||||
|
});
|
||||||
|
|
||||||
|
// Create settings class
|
||||||
|
class MyFirstPluginSettings extends BasePlugin<typeof settings> {
|
||||||
|
@Setting(settings.enabled)
|
||||||
|
enabled!: boolean;
|
||||||
|
|
||||||
|
@Setting(settings.customMessage)
|
||||||
|
customMessage!: string;
|
||||||
|
|
||||||
|
@Setting(settings.showEmoji)
|
||||||
|
showEmoji!: boolean;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Create settings instance
|
||||||
|
const settingsInstance = new MyFirstPluginSettings();
|
||||||
|
|
||||||
|
// Define the plugin
|
||||||
|
const myFirstPlugin: Plugin<typeof settings> = {
|
||||||
|
id: "my-first-plugin",
|
||||||
|
name: "My First Plugin",
|
||||||
|
description: "Adds a customizable welcome message to the SEQTA homepage",
|
||||||
|
version: "1.0.0",
|
||||||
|
|
||||||
|
// Link our settings
|
||||||
|
settings: settingsInstance.settings,
|
||||||
|
|
||||||
|
// Mark as beta (optional)
|
||||||
|
beta: true,
|
||||||
|
|
||||||
|
// Add some CSS styles (optional)
|
||||||
|
styles: `
|
||||||
|
.my-plugin-welcome {
|
||||||
|
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
|
||||||
|
color: white;
|
||||||
|
padding: 20px;
|
||||||
|
border-radius: 12px;
|
||||||
|
margin: 20px;
|
||||||
|
box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
|
||||||
|
text-align: center;
|
||||||
|
font-size: 18px;
|
||||||
|
animation: slideIn 0.5s ease-out;
|
||||||
|
}
|
||||||
|
|
||||||
|
@keyframes slideIn {
|
||||||
|
from {
|
||||||
|
opacity: 0;
|
||||||
|
transform: translateY(-20px);
|
||||||
|
}
|
||||||
|
to {
|
||||||
|
opacity: 1;
|
||||||
|
transform: translateY(0);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
.my-plugin-welcome .close-btn {
|
||||||
|
float: right;
|
||||||
|
background: rgba(255, 255, 255, 0.2);
|
||||||
|
border: none;
|
||||||
|
color: white;
|
||||||
|
padding: 5px 10px;
|
||||||
|
border-radius: 20px;
|
||||||
|
cursor: pointer;
|
||||||
|
font-size: 12px;
|
||||||
|
}
|
||||||
|
|
||||||
|
.my-plugin-welcome .close-btn:hover {
|
||||||
|
background: rgba(255, 255, 255, 0.3);
|
||||||
|
}
|
||||||
|
`,
|
||||||
|
|
||||||
|
// Main plugin function
|
||||||
|
run: async (api) => {
|
||||||
|
console.log("[My First Plugin] Starting up! 🚀");
|
||||||
|
|
||||||
|
// Wait for settings to load
|
||||||
|
await api.settings.loaded;
|
||||||
|
|
||||||
|
let welcomeElement: HTMLElement | null = null;
|
||||||
|
|
||||||
|
// Function to create the welcome message
|
||||||
|
const createWelcomeMessage = () => {
|
||||||
|
// Only show if enabled in settings
|
||||||
|
if (!api.settings.enabled) {
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Remove existing message if it exists
|
||||||
|
if (welcomeElement) {
|
||||||
|
welcomeElement.remove();
|
||||||
|
}
|
||||||
|
|
||||||
|
// Create the message element
|
||||||
|
welcomeElement = document.createElement("div");
|
||||||
|
welcomeElement.className = "my-plugin-welcome";
|
||||||
|
|
||||||
|
// Build the message content
|
||||||
|
let message = api.settings.customMessage;
|
||||||
|
if (!api.settings.showEmoji) {
|
||||||
|
// Remove emojis if disabled
|
||||||
|
message = message.replace(/[\u{1F600}-\u{1F64F}]|[\u{1F300}-\u{1F5FF}]|[\u{1F680}-\u{1F6FF}]|[\u{1F1E0}-\u{1F1FF}]|[\u{2600}-\u{26FF}]|[\u{2700}-\u{27BF}]/gu, '');
|
||||||
|
}
|
||||||
|
|
||||||
|
welcomeElement.innerHTML = `
|
||||||
|
<button class="close-btn" onclick="this.parentElement.remove()">×</button>
|
||||||
|
<div>${message}</div>
|
||||||
|
<small style="opacity: 0.8; margin-top: 10px; display: block;">
|
||||||
|
Powered by My First Plugin
|
||||||
|
</small>
|
||||||
|
`;
|
||||||
|
|
||||||
|
return welcomeElement;
|
||||||
|
};
|
||||||
|
|
||||||
|
// Function to add message to homepage
|
||||||
|
const addToHomepage = () => {
|
||||||
|
api.seqta.onMount(".home-page, .dashboard, [class*='home']", (homePage) => {
|
||||||
|
console.log("[My First Plugin] Found homepage, adding welcome message");
|
||||||
|
|
||||||
|
const message = createWelcomeMessage();
|
||||||
|
if (message) {
|
||||||
|
// Add to the top of the homepage
|
||||||
|
homePage.insertBefore(message, homePage.firstChild);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
};
|
||||||
|
|
||||||
|
// Add message when plugin starts
|
||||||
|
addToHomepage();
|
||||||
|
|
||||||
|
// Re-add message when user navigates to homepage
|
||||||
|
api.seqta.onPageChange((page) => {
|
||||||
|
console.log("[My First Plugin] Page changed to:", page);
|
||||||
|
if (page.includes("home") || page.includes("dashboard")) {
|
||||||
|
// Small delay to let the page load
|
||||||
|
setTimeout(addToHomepage, 500);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
// Listen for settings changes and update the message
|
||||||
|
api.settings.onChange("enabled", (enabled) => {
|
||||||
|
console.log("[My First Plugin] Enabled setting changed:", enabled);
|
||||||
|
if (enabled) {
|
||||||
|
addToHomepage();
|
||||||
|
} else if (welcomeElement) {
|
||||||
|
welcomeElement.remove();
|
||||||
|
welcomeElement = null;
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
api.settings.onChange("customMessage", (newMessage) => {
|
||||||
|
console.log("[My First Plugin] Message changed:", newMessage);
|
||||||
|
if (welcomeElement && api.settings.enabled) {
|
||||||
|
// Update existing message
|
||||||
|
addToHomepage();
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
api.settings.onChange("showEmoji", (showEmoji) => {
|
||||||
|
console.log("[My First Plugin] Show emoji changed:", showEmoji);
|
||||||
|
if (welcomeElement && api.settings.enabled) {
|
||||||
|
// Update existing message
|
||||||
|
addToHomepage();
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
// Return cleanup function (called when plugin is disabled)
|
||||||
|
return () => {
|
||||||
|
console.log("[My First Plugin] Cleaning up...");
|
||||||
|
if (welcomeElement) {
|
||||||
|
welcomeElement.remove();
|
||||||
|
welcomeElement = null;
|
||||||
|
}
|
||||||
|
};
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
|
export default myFirstPlugin;
|
||||||
|
```
|
||||||
|
|
||||||
|
## How to Use This Example
|
||||||
|
|
||||||
|
### Step 1: Create the Plugin File
|
||||||
|
1. Create a new folder: `src/plugins/built-in/my-first-plugin/`
|
||||||
|
2. Create `index.ts` in that folder
|
||||||
|
3. Copy the code above into `index.ts`
|
||||||
|
|
||||||
|
### Step 2: Register the Plugin
|
||||||
|
Add this to `src/plugins/index.ts`:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// Add this import at the top
|
||||||
|
import myFirstPlugin from "./built-in/my-first-plugin";
|
||||||
|
|
||||||
|
// Add this line where other plugins are registered
|
||||||
|
pluginManager.registerPlugin(myFirstPlugin);
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 3: Test It
|
||||||
|
1. Run `npm run dev`
|
||||||
|
2. Reload your extension in Chrome
|
||||||
|
3. Visit a SEQTA page
|
||||||
|
4. You should see your welcome message!
|
||||||
|
5. Open BetterSEQTA+ settings to customize it
|
||||||
|
|
||||||
|
## Key Concepts Explained
|
||||||
|
|
||||||
|
### 1. Plugin Structure
|
||||||
|
```typescript
|
||||||
|
const myPlugin: Plugin = {
|
||||||
|
id: "unique-id", // Must be unique across all plugins
|
||||||
|
name: "Display Name", // Shown in settings
|
||||||
|
description: "What it does", // Shown in settings
|
||||||
|
version: "1.0.0", // Plugin version
|
||||||
|
settings: settingsObject, // User-configurable options
|
||||||
|
styles: "/* CSS here */", // Optional CSS styles
|
||||||
|
run: async (api) => { // Main plugin code
|
||||||
|
// Your code here
|
||||||
|
}
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Settings System
|
||||||
|
```typescript
|
||||||
|
// Define what settings your plugin has
|
||||||
|
const settings = defineSettings({
|
||||||
|
myOption: booleanSetting({
|
||||||
|
default: true,
|
||||||
|
title: "My Option",
|
||||||
|
description: "What this option does"
|
||||||
|
})
|
||||||
|
});
|
||||||
|
|
||||||
|
// Use in your plugin
|
||||||
|
if (api.settings.myOption) {
|
||||||
|
// Do something
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. SEQTA Integration
|
||||||
|
```typescript
|
||||||
|
// Wait for elements to appear
|
||||||
|
api.seqta.onMount(".some-selector", (element) => {
|
||||||
|
// Modify the element
|
||||||
|
});
|
||||||
|
|
||||||
|
// Detect page changes
|
||||||
|
api.seqta.onPageChange((page) => {
|
||||||
|
if (page === "home") {
|
||||||
|
// User navigated to homepage
|
||||||
|
}
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Cleanup
|
||||||
|
Always return a cleanup function to remove your changes when the plugin is disabled:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
run: async (api) => {
|
||||||
|
// Add your features
|
||||||
|
|
||||||
|
return () => {
|
||||||
|
// Remove your features
|
||||||
|
};
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Customization Ideas
|
||||||
|
|
||||||
|
Want to modify this example? Here are some ideas:
|
||||||
|
|
||||||
|
1. **Change the styling**: Modify the CSS to use different colors, animations, or layouts
|
||||||
|
2. **Add more settings**: Number settings, select dropdowns, hotkeys
|
||||||
|
3. **Different trigger**: Show on different pages, or based on time of day
|
||||||
|
4. **Add interactions**: Buttons that do things when clicked
|
||||||
|
5. **Store data**: Use `api.storage` to remember user preferences
|
||||||
|
6. **Communicate with other plugins**: Use `api.events` to send/receive events
|
||||||
|
|
||||||
|
## Next Steps
|
||||||
|
|
||||||
|
Once you've got this working:
|
||||||
|
|
||||||
|
1. **Experiment**: Try changing things and see what happens
|
||||||
|
2. **Read other plugins**: Look at the built-in plugins for inspiration
|
||||||
|
3. **Check the API docs**: Learn about all available API functions
|
||||||
|
4. **Share your creation**: Show it off in Discord!
|
||||||
|
|
||||||
|
## Need Help?
|
||||||
|
|
||||||
|
- 💬 Ask in our [Discord server](https://discord.gg/YzmbnCDkat)
|
||||||
|
- 📚 Read our [Plugin Development Guide](./README.md)
|
||||||
|
- 🐛 Check the [Troubleshooting Guide](../TROUBLESHOOTING.md)
|
||||||
|
- 📝 Open an issue on GitHub
|
||||||
|
|
||||||
|
Happy coding! 🎉
|
||||||
Reference in New Issue
Block a user