NPM Package Structure & Organization

[mihar-22]

We've recently finished initial work on some tooling and are starting to migrate Vidstack Player over. Release notes will follow when we're done but in the meantime I wanted to propose a new structure for our packages. I'd love to hear any thoughts and suggestions!

Requirements

Our NPM package structure and organization needs to support the following:

• General entry point for importing TS types including element classes, events, interfaces, stores, etc.
• For a developer to import and register all custom elements.
• Import and register individual custom elements such as vds-media, vds-play-button, etc.
• Import and register bundles and individual elements over a CDN.
• Installing and using different products. Today it's just the player, but we do have both an uploader and analytics lib planned for the future. They might not be big enough to warrant their own packages. What if we add more products (e.g., playlists, chat, ...)?
• JS frameworks - starting with React but we'll also work on Vue, Svelte, Preact, and Solid.
• UI libs as headless and skinned - import components and possibly CSS stylesheets.
• Different player skins - import components and CSS stylesheets.

Current Organization

We currently have the packages organized like so @vidstack/{product}-{framework}:

• @vidstack/player
• @vidstack/player-react

Likely Future Packages:

• @vidstack/player-{vue,svelte,solid}
• @vidstack/analytics
• @vidstack/analytics-{react,...}
• @vidstack/uploader

Proposed Organization

We've been discussing simplifying the package structure to @vidstack/{framework}.

• Core: vidstack
• React: @vidstack/react
• Vue: @vidstack/vue

Pros:

• You'll only need to install a single Vidstack player package (e.g., npm i @vidstack/react). With this you'll have access to any current and future products as they're released.
• Kind of easier to document if it's a single package for all products.
• Only a single "monolith" package to manage per framework. Easier to keep all configurations (build/tests/storybook) and shared code together for each framework without resorting to some kind of core/foundation packages. This might be the biggest reason to consider this proposal.
• We can use the vidstack package as our core and include all base types, utilities, and CSS themes/skins in one place.

Cons:

• Larger package size (not bundle size) as it houses more products/features. Some devs may not like the idea of installing products they're not using.
• More editor suggestions might appear as TS will pick up all product type declaration (.d.ts) files.
• Longer build processes that might be hard to disentangle as all products (player/analytics/...) will be in a single place.
• We won't be able to build polyrepos on GitHub around products. We had mentioned we want to work towards polyrepos so it's easier for newcomers to identify the repo (e.g., this one is for the player), but the overhead of managing it particularly around separate package symlinks, builds, and so on might be a nightmare. This is both a pro/con.

Still thinking if there's any other real concerns...

Package Anatomy

• General import path for types, classes, events:
  • vidstack
• Import and register custom elements:
  • import "vidstack/elements/all.js"
  • Or, indivdually like so import "vidstack/elements/vds-media.js".
  • Frameworks will be import specifiers from a base pathimport { Media } from "@vidstack/react";
• Import over a CDN:
  • <script src="cdn.jsdelivr.net/npm/vidstack/all+esm" type="module">
  • Or, individually like so <script src="cdn.jsdelivr.net/npm/vidstack/vds-media+esm" type="module">

⚠️ This next part is a gray area as we're not sure how to tackle UI and skins yet.

• UI: default skinned components. Prebuilt components with simple customization options to get you up and running quickly.

  • import "vidstack/elements/vds-play-button.js"
  • import { PlayButton } from "@vidstack/react"

• Headless UI: today this is the default. We think it'll be easier to onboard if headless isn't the default recommendation... not sure though.

  • import "vidstack/elements/headless-ui/vds-play-button.js"
  • import { PlayButton } from "@vidstack/react/headless-ui"

• Skins:

  • import "vidstack/elements/vds-community-skin.js"
  • import "vidstack/elements/plyr-skin.js"
  • import { PlyrSkin } from "@vidstack/react".

• Skin Styles

  • import "vidstack/styles/plyr.css"
  • import "vidstack/styles/plyr-vars.css"

CSS for skins will follow BEM structure and we won't be using Shadow DOM. This will make it super easy to inspect the UI in devtools and customize as desired.

Examples

Here's some links to existing framework-agnostic OSS packages that we're looking closely at for any inspiration.

• Ionic
• AG Grid
• TanStack
• Storybook

[pietrop]

Sounds good to me, I like the idea of eg getting everything you need from React with one package @vidstack/player-react.

UI

For the UI would you be supporting this as well?

- import { PlayButton } from "@vidstack/react/headless-ui"
+ import PlayButton  from "@vidstack/react/headless-ui/PlayButton"

I don't know if this is still valid or if bundlers and tree shaking has moved on since, but I remember this piece of documentation from React Bootstrap about Importing Components from a while back.

You should import individual components like: react-bootstrap/Button rather than the entire library. Doing so pulls in only the specific components that you use, which can significantly reduce the amount of code you end up sending to the client.

import Button from 'react-bootstrap/Button';

// or less ideally
import { Button } from 'react-bootstrap';

Package & folder structure

Another one that might be worth taking a look at to see how they handle Cherry Picking 🍒 and bundling under the hood.

• shoelace.style
• github.com/shoelace-style/shoelace

---

Hope this helps 🙏

Thanks for all your work on this 🚀

[mihar-22]

Sounds good to me, I like the idea of eg getting everything you need from React with one package @vidstack/player-react.

Did you mean @vidstack/react here? 😅

For the UI would you be supporting this as well?

Nope, modern bundlers should handle treeshaking just fine because we can declare side effectful files in package.json. Might be outdated docs section or specific to React Bootstrap.

Another one that might be worth taking a look at to see how they handle Cherry Picking 🍒 and bundling under the hood.

Shoelace is awesome but not a fan of dist/ path imports. We can avoid that with the new exports field in package.json and manually adding some declaration file redirects in package root.

Thanks for all your work on this 🚀

Thanks right back!

[pietrop]

Did you mean @vidstack/react here? 😅

Ahah, yes!

Nope, modern bundlers should handle treeshaking just fine because we can declare side effectful files in package.json. Might be outdated docs section or specific to React Bootstrap.

ok, that's great!

Shoelace is awesome but not a fan of dist/ path imports. We can avoid that with the new exports field in package.json and manually adding some declaration file redirects in package root.

cool!

It all seems pretty solid, the second part on the skins and UIs, it's kind of hard to comment on that without more info on the architecture and usage of those components, but I am looking forward to see how it shapes up and will circle back when there's more info 🙏 🚀