Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Decide the pack catalog distribution model and implement it

Open
  • Is something wrong?
#52 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
typescript
Domain
full-stack

Research direction

Start by reading docs/adr/0006-offline-first-pwa-on-github-pages.md and docs/architecture.md, section 9, to understand the existing constraints and pack sources. Then inspect packages/cli/src/commands/build.ts, apps/web/src/logic/catalog.ts, and apps/web/src/services/packs.ts. Done means the distribution decision is recorded in an accepted ADR, catalog validation and CI checks are documented and implemented, catalog packs work offline through the listed player flows, the end-to-end test verifies no cross-origin requests, and the offline file stays within the ADR’s budget.

Written by the indexing model from the issue text.

Description

area: content area: infra area: web priority: medium type: decision

Context

Packs are bundled into the player at build time (the lexvm-catalog/1 index.json from lexvm build) or imported from files. As community packs grow, bundling everything into the PWA and into lexvm-offline.html stops scaling, and players need a way to discover packs. At the v0.1 pull request, with two packs, lexvm-offline.html is 660 KB (209 KB gzip), and the noir pack alone is a 100 KB .lexpack.json. Constraints: no server, no accounts, no tracking, no network requests beyond the player's own files (ADR 0006), offline-first, and no pack enters the catalog without passing lexvm check.

Options

  • A. Status quo: every pack in this repository is bundled. Simple, but the offline file and the precache grow with every pack.
  • B. Same-origin catalog on GitHub Pages: all packs stay in this repository; the catalog lists them; only featured packs are bundled and precached; the others are downloaded on demand from the same origin and stored on the device.
  • C. A separate registry repository with its own Pages site. The player would fetch a cross-origin index, which needs an amendment to ADR 0006 and a content security policy for it.
  • D. GitHub Releases as the distribution channel. Cross-origin, with CORS and rate-limit issues.

Proposed: B.

Scope

  • ADR for the chosen model.
  • Catalog format (a new version if needed): id, version, hash, language, estimated length, license, author, size, content notes; generated and validated in CI.
  • Library: a "More adventures" section with download, size, update notice when the hash changes (using the existing replay flow) and delete.
  • lexvm-offline.html contains only the featured packs.

Acceptance criteria

  • The ADR is accepted.
  • The catalog format is documented, and CI fails if a listed pack does not pass lexvm check.
  • The player lists, downloads, stores, updates and deletes catalog packs, and downloaded packs play offline.
  • An end-to-end test asserts that no cross-origin request is made.
  • The size of lexvm-offline.html stays within a budget recorded in the ADR.

References

  • packages/cli/src/commands/build.ts
  • apps/web/src/logic/catalog.ts
  • apps/web/src/services/packs.ts
  • docs/adr/0006-offline-first-pwa-on-github-pages.md
  • docs/architecture.md (section 9, Pack sources)
Dominant language
TypeScript
Stars
0
Forks
0
Avg merge
28m
Merged PRs (30d)
2

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from nullthrone/lexvm

All issues in nullthrone/lexvm

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.