Including Lit as a dependency

[maledr5]

As part of our bundling topic, we have an open question on how to include Lit package within our components. Currently we do not declare it as a dependency so pilot consumers have to install it separately.

Options proposed are:

• include it as a peerDependency so that consumers know they have to install it separately (and not from an error message)
• include it as a dependency, so that it gets automatically installed when consumers install our package

From an initial discussion we captured some points:

• ideally consumers don't have to install Lit or any additional dependencies themselves
• we don't want to bundle Lit
• we could follow Lit Publishing Guide to figure out best practices

The goal of this discussion is to capture ideas for next steps to tackle, most likely, things we will need to spike.

💡 This discussion is part of the whole bundling topic. If you have any other ideas or concerns around bundling in general, feel free to drop them here as well, and we'll see if we need to branch some of them to a new discussion.

[ashleynolan]

Having read a bit more about it since chatting about it last week, I think that Lit should be a dependency for our components, so that it gets installed automatically when consumers install our package. So, therefore it would get bundled as part of each component, with the expectation that consuming applications are able to dedupe it through a combination of using NPM and treeshaking their code.

Just a few added points around this topic (just to make sure they're documented as part of this discussion):

• Lit recommends that it is a dependency for components, and then ensuring components are published unminified so that NPM and the consuming application can handle deduplicating the common packages. Ensuring we don't minify our components is the important part here (we currently do, and so should provide a dist version of our package that is not minified).
• We should discuss whether we should follow Lit's recommendation and not bundle polyfills as part of our components. For example, we currently do bundle polyfills for pie-modal (dialog-polyfill) and for pie-button (element-internals-polyfill). The outcome of this should be that we document how we handle polyfills for components and if they are left to consuming applications to include, ensure we document that as part of our specific component documentation.
• One thing for us to test as part of this approach (not as an immediate concern, but something we should likely be aware of for consumers in the future) is by bundling Lit as part of each component, we should likely explore what would happen if a consuming app decided to use two components which bundled different versions of Lit. This is most likely something we should handle through our releases nd comms, but is something we should be aware of potentially happening if consumers try to update one component while leaving others on older versions.

[maledr5]

Hey, I took some time to test different options of using lit as a Dependency or PeerDependency, and also did some reading on what each of this mean. Wanted to share my findings here as it seems to be the best place to add this discoveries:

What use of dependencies will bundle lit in our distribution?

I found that this is 100% a Vite configuration. When removing lit from rollUp external in our Vite config, no matter what form we use (no Dependency, Dependency, Peer Dependency) lit will still be bundled in our distribution. When adding it back to rollUp external in our Vite config, then it is not bundled no matter what form we use (no Dependency, Dependency, Peer Dependency).

My take

From my understanding, litcould be either a dependency or peerDependency.

PeerDependencies seem to have been created for specific use cases, like plugins. Based on this, it doesn't make sense to include 'lit' as a peerDependency, as our components are not a Lit plugin.

On the other hand, I noticed that they are heavily used for packages in the React ecosystem including MUI. So I understand it might come handy to have them as PeerDependency to favor consumers that actually use Lit as a dependency!

I think it might be worth asking this to the lit team, as their recommendation was to use lit as a Dependency, and spectrum and shoelace follow this pattern.

For now I think we can follow their suggestion using lit as Dependency, and move it to PeerDependency if we discover is a better approach.

[jamieomaguire]

Thanks for setting up this discussion @maledr5

I just wanted to record some thoughts whilst they're still in my head!

In my opinion, it makes sense to list some packages as dependencies of our components whilst not bundling them (via rollup configuration, for example). An example of this being lit.

My thoughts on the two terms:

Dependency - Our components require these packages to work, however, it is not reasonable to expect a consuming application to already have these packages installed. Example: A Nuxt application would have no reason to install lit or @lit-labs/ssr. Furthermore, although some apps may install lit as an application framework, I would consider these edge cases. In these cases we should strive for solid communication on lit version compatibility between the app and components.

peerDependency - These are still required by our package, but there is a reasonable expectation that our consumers would use these packages themselves anyway. Example: A React component library would expect a consuming application to already have React installed.

I am sure there are numerous examples that debunk this approach but I think it helps to simplify.

Therefore in conclusion I think lit should be a dependency, along with any other Lit helper packages but they should not be bundled in our components. This is based on the assumption that package managers will auto install missing dependencies the same way that Yarn does.