Reasoning for the new decorator import syntax

[mckamyk]

Forgive me if this is the wrong category, but this has been bugging me since moving to lit3. Obviously, its not a real issue, but I was curious as to the reasoning behind this change and what the motivations were.

In the previous version, you imported decorators such as query and property from the lit-element package.

import {LitElement, html, css, query, property} from 'lit-element';

In the new version, the imports are now in two different lines, and you have to specify .js at the end of the import.

import {LitElement, html, css} from 'lit';
import {query, property} from `lit/decorators.js`;

My questions are,

1. Why aren't the decorators exported from the lit package?
2. What impacts to typescript parsing are there, I'm assuming there' s a declaration file casting the types.
3. What impacts to tree-shaking are there, in respects to bundling with Webpack and Rollup?
4. (or 3b) Is importing from lit/decorators/query.js required to enable tree-shaking?

[justinfagnani]

The only reason is so that non-decorator users don't pay the payload costs of the decorator implementations. This also applies to future transforms that compile the decorators out - once the decorators are removed we can remove the import.

I don't think there are any impacts to TypeScript parsing, but I might not understand the question.

Not loading the files improves native tree-shaking, ie, the browser doesn't load what you don't import. I'm not sure how well code-rewriting tree-shaking worked before, but this is strictly better since it doesn't rely on it.

[mckamyk]

I see. The separation was intended for consumers that aren't doing an active bundling/tree-shaking step. I'd imagine there's no difference in pulling it out for tree-shakers. But I support that decision to pull it out.

My curiosity with typescript was the fact that you're importing a .js file, which I can assume doesn't track types. This could be (and apparently is) fixed with a relevant .d.ts file in the right place. I do believe that even with the new syntax, the decorators get proper type hinting/safety, so its really a non-issue.

So, to narrow down, I understand the reason to remove the decorators from the main lit package. My other curiosity is why is .js added to the import string. I assume because otherwise it would be ambiguous, as lit/decorators could either be pointing at the js file, or the folder containing individual decorators' files.

Looking in your package.json, in the exports field, I see ./decorators.js and ./decorators/ are there, pointing to their corresponding locations. Why is ./decorators.js not simply ./decorators. Making this change satisfies webpack at least, letting me import {state} from 'lit/decorators'. Would this break (rather, bloat) the non-bundling browser imports?

Not arguing, just wanting to learn more about how this stuff works.

[mario-d-s]

@justinfagnani I'm also curious about the need to specify .js in the import specifier!
This actually bit me, cause using Rollup + @rollup/plugin-node-resolve, it doesn't know how to resolve lit/decorators and the error is a bit vague.

Especially as a TypeScript user this is kind of confusing (.js vs .ts) and I imagine it introduces a hurdle for a lot of developers cause this is this the first time I see it making a difference.

I'm in doubt of opening an issue on Rollup as well, but I don't know what should be the expected behavior here. Should the Rollup plugin properly resolve the decorators.js export if you import it as lit/decorators?

[mohe2015]

I'm not affiliated with lit in any way but I think https://lit.dev/docs/tools/requirements/ answers that question.

Why bare module specifiers? Bare module specifiers let you import modules without knowing exactly where the package manager has installed them. A standards proposal called Import maps is starting to ship, which will let let browsers support bare module specifiers. In the meantime, bare import specifiers can easily be transformed as a build step. There are also some polyfills and module loaders that support import maps.

Import maps would probably not (easily) work with the paths without .js as I assume thats an additional resolve step that is not obvious

[aomarks]

Yes, import maps are the reason the .js extension is required for imports. For import maps to be compatible with extensionless imports, the import map would need to include an explicit entry for every file instead of using prefix mappings, and would therefore become much larger. We are looking forward to the not-too-distant future where import maps will allow importing lit and other libraries without import-rewriting build steps, and we want the import maps to be small so that they download quickly.

See also https://lit.dev/docs/tools/publishing/#include-file-extensions-in-import-specifiers and #1986 (comment)

[samuelstroschein]

The DX is negatively impacted by unbundling lit exports. Autocomplete is flaky with many different import paths; developers need to look up the docs where something is imported from, and the import list quickly gets long.

I assume that most lit developers use a bundler. Hence, three-shaking is on by default. If that's the case, I propose to switch the default import case from unbundled to bundled.

-import { html, nothing } from "lit";
-import { customElement, state } from "lit/decorators.js";
-import { Task } from "@lit/task";
-import { classMap } from "lit/directives/class-map.js";
-import { repeat } from "lit/directives/repeat.js";
+import { html, repeat, state, Task, classMap, customElement, nothing } from "lit"

If JS devs care about minimizing their import size, they should use a bundler or import unbundled imports.

-import { html, nothing } from "lit"
+import { html, nothing } from "lit/html.js"

[samuelstroschein]

The example is from a smallish real-world component. Five imports, potentially more, that could be one for the (assumed) majority of users. I have to look up where to import something from all the time. Granted, auto-complete doesn't properly work. But, I think TypeScript is also confused by the many exports.

[justinfagnani]

TypeScript shouldn't be confused by the number of imports.

From experience, bundler tree-shaking doesn't always work, and we do have a lot of people that don't use bundlers, at least in development. Importing only what you need to use is the platform native tree-shaking. It not only makes loading the libraries over the network faster, but it makes tools like bundlers faster since they don't have to load, parse, and analyze as much code.

As decorators are standardized and shipped across browsers, and we move away from non-decorator ways of declaring reactive properties, we will likely include at least @property and @state in the core library. But the others are entirely optional.

Things like Task are entirely separate packages too. They are not core and could be replaced by alternate approaches.

[samuelstroschein]

I made my point. I understand the technical desire to keep things separate. But, the DX is impacted to the degree that using lit "is annoying". No matter how sound the (minor) technical reason might be :)