Skip to content

Conversation

@northword
Copy link
Collaborator

@northword northword commented Sep 3, 2025

Background

The current template provides example.ts, which mainly uses a class + static methods structure to organize example logic.
While this approach looks straightforward in the demo stage, it reveals several issues during real development or user customization.

  1. User habits

    • Many developers build directly on top of the template without refactoring variable names, method names, or file structures in the example file.
    • As a result, example logic often gets mixed with production logic, reducing code quality and readability.
  2. Redundant code is hard to clean up

    • Methods inside a class are all statically attached. Even if unused, they are difficult for tree-shaking to remove.
    • This can leave a large amount of unused example code in the final bundle.
  3. Poor modular maintainability

    • Concentrating all example logic in a single class makes it harder to split and maintain by feature later.
    • Different functional modules (e.g., notifier, shortcuts, UI, helpers) lack clear boundaries.
  4. Classes provide no real benefit here

    • All methods are static, so no state can be stored via instantiation. In essence, they behave the same as exported functions.
    • Instead, the extra class wrapper just adds unnecessary cognitive load.

Plan

  1. Refactor example.ts into a functions + module-scope variables model.
  2. Split logic into multiple feature-based modules (notifier, shortcuts, UI, prompts, helpers, etc.).
  3. Centralize the scheduling of each module’s register/unregister methods in hooks.ts.
  4. Keep unregister only for the few modules that need state (e.g., notifier, stylesheet). Other modules will expose only register.

Expected outcomes:

  • Simpler and clearer: Functions are naturally stateless. In rare cases where state is needed (e.g., notifier IDs), module-scope variables are sufficient.
  • Tree-shaking friendly: Unused functions can be removed automatically, whereas unused class methods are harder to remove.
  • More maintainable and maybe out of the box: Splitting by feature (notifier, shortcuts, UI, helpers, etc.) makes the codebase easier to maintain and extend.
  • Lower misuse risk: Users can more easily understand and remove example logic they don’t need (although this means the @example decorator can no longer be used).

Others

I'm not sure if this modification is reasonable; it needs to be discussed.

@windingwind
Copy link
Owner

The zotero7 branch is achieved and before the zotero 8 official release i think we'll have some time for the refactor. Generally looks good to me

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants