Repository Structure

Monorepo Structure

The repository uses Nx for task orchestration and pnpm workspace for dependency management. Main directories are:

• Directorypackages/

  • Directorycore/ Core components in Vanilla JS

    • …
  • Directoryreact/ React bindings for core

    • …
  • Directoryvue/ Vue bindings for core

    • …
  • Directoryreact-full/ Ready-to-use full player components (React only)

    • …
  • Directoryttml/ TTML parser and processing library

    • …
  • Directorylyric/ Lyrics parser and processing library (TTML depends on the ttml package)

    • …
  • Directorydocs/ Astro + Starlight docs site

    • …
  • Directoryplayground/ Example projects for development and testing

    • Directorycore/ Example using core

      • …
    • Directoryreact/ Example using React bindings

      • …
    • Directoryvue/ Example using Vue bindings

      • …
    • Directoryreact-full/ Example using full player components

      • …
• Directory.github/

  • Directoryworkflows/

    • …
  • Directoryscripts/

    • …

Nx Release Groups

Release config in nx.json includes two major groups:

• core-bundle: three packages share the same version:
  • @applemusic-like-lyrics/core
  • @applemusic-like-lyrics/react
  • @applemusic-like-lyrics/vue
• Other packages are versioned independently:
  • @applemusic-like-lyrics/lyric
  • @applemusic-like-lyrics/react-full
  • @applemusic-like-lyrics/ttml

Dependency Graph

Run:

pnpm nx graph

to view the full dependency graph.

When bumping versions, if a dependency package changes, dependent packages may also be bumped automatically even when their own code is unchanged.

CLI

Library Development

Nx provides convenient aliases; you do not need to type the @applemusic-like-lyrics/ prefix.

For example, to build @applemusic-like-lyrics/react:

pnpm nx build react

Nx resolves dependencies automatically, so it builds core first, then react.

We provide web apps in package/playground for testing, based on Vite with HMR support. We added forwarding entries for core, react, vue, and react-full, so to start a matching environment:

# Start dev server for package/playground/core
pnpm nx dev core

# Same for others
pnpm nx dev react
pnpm nx dev vue
pnpm nx dev react-full

To build all libraries:

pnpm build:libs

It builds all packages in parallel with dependency-aware ordering.

Docs Development

Similarly, the docs site alias is docs, with these commands:

# Start docs dev server
pnpm nx dev docs
# Build docs site
pnpm nx build docs

Dependencies are handled automatically.