docs: document sharing helper functions/constants across user scripts (#622)

[chhoumann]

Summary

Documents how to share helper functions and constants across QuickAdd user scripts — the most-requested gap in #622. This is docs-only: it describes an existing, runtime-verified capability (a user script can require() a shared .js module by absolute path) that was never written down.

Adds a new ## Sharing Code Between Scripts section to UserScripts.md in both the current (Next) docs and the served version-2.13.1 snapshot, plus a cross-link from the ### Variables section so users on the params.variables workaround path discover it.

Why

The pattern works today because every user script is executed with a require argument (src/utils/userScript.ts:36), but it was undocumented, so the only answer people found was passing data through params.variables between chained scripts — which the reporter rightly called convoluted, and which can't share functions at all.

What the section covers

• The require(absolute-path) pattern, building the path at runtime from app.vault.adapter.getBasePath().
• Desktop-only caveat with an instanceof obsidian.FileSystemAdapter guard (mobile has no require).
• Security caveat (require runs arbitrary code immediately).
• Portability/Sync caveat (never hardcode a literal absolute path).
• Reload/cache caveat, with the correct cache-bust via window.require (the script-scoped require is a thin wrapper with no .cache/.resolve).
• Cross-platform fallbacks.

Verification

• Proven end-to-end in an isolated Obsidian vault: a real Macro choice → quickadd:run → user script require'd a shared module and returned hello from shared module :: 1,234,567 USD (constant + function + constant). Cache caveat and the window.require cache-bust both confirmed live.
• cd docs && pnpm build passes (onBrokenLinks: 'throw'); both new anchors resolve.

Scope

Out of scope by design: a relative-require module resolver (needs synthetic __dirname, still desktop-only, thin demand) and any runtime code change to userScript.ts.

Closes #622

Summary by CodeRabbit

• Documentation
  • Enhanced User Scripts guide with new guidance on sharing helper functions and constants between scripts
  • Added clarification on params.variables for data transfer between steps
  • Included information on module caching behavior, desktop-only constraints, and cross-platform implementation options

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 79614c2d-3609-4c2f-8ede-0ce04136686b

📥 Commits

Reviewing files that changed from the base of the PR and between eb2a4b6 and 71d6531.

📒 Files selected for processing (2)

• docs/docs/UserScripts.md
• docs/versioned_docs/version-2.13.1/UserScripts.md

---

📝 Walkthrough

Walkthrough

Two UserScripts.md files (current and versioned 2.13.1) receive identical new content: a "Sharing Code Between Scripts" section covering require()-based shared module loading with runtime absolute path resolution, desktop-only caveats, cache-busting, and cross-platform alternatives, plus a tip callout in the Variables subsection.

Changes

UserScripts Documentation – Shared Code Guidance

Layer / File(s)

Summary

Sharing Code Between Scripts section and variables tip docs/docs/UserScripts.md, docs/versioned_docs/version-2.13.1/UserScripts.md

Adds the "Sharing Code Between Scripts" subsection documenting require() usage with a runtime-computed absolute path via getBasePath(), desktop-only limitations, require cache-busting snippet, and cross-platform alternatives. Also adds a tip callout in the Variables subsection clarifying that params.variables is for inter-step data and pointing to the new shared-module section for reusing functions/constants.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~4 minutes

Poem

🐰 Hippity-hop, no more copy-paste dismay,
A shared .js module to brighten your day!
require() the helpers, resolve the right path,
Bust the cache gently and sidestep the wrath.
One function, many scripts — the warren rejoice,
The docs now ring out with a clear, hoppy voice! 🎉

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: documenting how to share helper functions and constants across user scripts, directly matching the PR's primary objective.
Linked Issues check	✅ Passed	The PR fully addresses issue #622 by documenting an existing require() pattern for sharing helper functions and constants across user scripts, providing the straightforward solution requested.
Out of Scope Changes check	✅ Passed	All changes are in-scope: the PR adds documentation about sharing code patterns to both current and versioned UserScripts guides, with a cross-link from Variables section, all directly supporting the stated objective.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chhoumann/622-userscript-helper-docs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cloudflare-workers-and-pages]

Deploying quickadd with    Cloudflare Pages

Latest commit:	71d6531
Status:	✅  Deploy successful!
Preview URL:	https://7b933925.quickadd.pages.dev
Branch Preview URL:	https://chhoumann-622-userscript-hel.quickadd.pages.dev

View logs