docs: add lnbits frontend gotchas + extension-dev reference
Two new docs to round out the lnbits-specific reference set:
docs/lnbits-frontend-gotchas.md — the Vue/Quasar UMD traps that don't
manifest under the build-step model most tutorials assume. Sections:
- No self-closing tags. UMD-loaded templates are parsed by the
browser's HTML parser, which doesn't honor self-close on non-void
elements; nesting silently breaks. Fine in .vue SFCs because the
build step rewrites them — but lnbits templates aren't SFCs.
- CSS specificity vs Quasar utilities. LNbits applies !important
overrides on .text-caption / .text-grey-*; class-based rules in
extension pages lose. Reach for inline :style bindings or static
style="" attrs instead.
- Cache busting via ?v={server_startup_time}. Bumping JS requires a
server restart; templates re-render every request.
- Dark-mode color discipline. bg-{color}-1 utilities don't get a
default text-inversion in dark theme; pair every pale background
with an explicit text class.
docs/lnbits-extension-dev.md — auth + testing + migration pattern.
Sections:
- Auth decorators table: require_invoice_key, require_admin_key,
check_admin, check_super_user. The require_admin_key vs
check_admin distinction is the most common misuse — one is
wallet-level write access (any user), the other is instance admin.
- Testing: FakeWallet for CRUD/API/UI, regtest only for real
Lightning behavior. Why the dev CLI defaults to --fakewallet.
- The migrations_fork.py pattern: keep migrations.py byte-identical
to upstream, put fork-only schema deltas in a sibling file loaded
under <ext>_fork in dbversions. Covers: architecture facts
(dbversions in core DB, no cross-DB atomicity → idempotent
migrations mandatory), squash recipe for adoption, one-time
dbversions surgery for installs that previously ran old fork
migrations, the upstream-overlap rebase scenario.
Both linked from README "Further reading". No personal identity in
either file.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
parent
0a5713c704
commit
1a75a04c2f
3 changed files with 260 additions and 2 deletions
14
README.md
14
README.md
|
|
@ -239,8 +239,18 @@ lb fix-issue-123 # cd ~/dev/lnbits/fix-issue-123
|
|||
- [`docs/lnbits-workspace-notes.md`](docs/lnbits-workspace-notes.md) —
|
||||
practical gotchas and design constraints for day-to-day lnbits work:
|
||||
port choice, `LNBITS_SRC` build-context traps, the
|
||||
extension-folder-upgrade-wipes-fork issue, Nostr key handling,
|
||||
CLINK protocol scope, fork versioning.
|
||||
extension-folder-upgrade-wipes-fork issue, settings precedence
|
||||
(`.env` vs DB), Nostr key handling, CLINK protocol scope, fork
|
||||
versioning.
|
||||
- [`docs/lnbits-extension-dev.md`](docs/lnbits-extension-dev.md) —
|
||||
building and maintaining LNbits extensions: auth-decorator
|
||||
distinctions, FakeWallet vs regtest testing strategy, the
|
||||
`migrations_fork.py` pattern for keeping fork-only schema deltas
|
||||
out of upstream-tracked `migrations.py`.
|
||||
- [`docs/lnbits-frontend-gotchas.md`](docs/lnbits-frontend-gotchas.md) —
|
||||
Vue/Quasar UMD traps in lnbits page templates: no self-closing
|
||||
tags, CSS specificity vs Quasar's `!important` utilities, cache
|
||||
busting via `?v={server_startup_time}`, dark-mode color discipline.
|
||||
|
||||
## Contributing to this scaffold
|
||||
|
||||
|
|
|
|||
Reference in a new issue