From 7db35bcd65208b514e18d5c9914471368acda7e6 Mon Sep 17 00:00:00 2001 From: Andrew Jakubowicz Date: Mon, 14 Aug 2023 17:29:40 -0700 Subject: [PATCH 1/7] Initial lit-labs/compiler readme --- packages/labs/compiler/README.md | 93 ++++++++++++++++++++++++++++++-- 1 file changed, 90 insertions(+), 3 deletions(-) diff --git a/packages/labs/compiler/README.md b/packages/labs/compiler/README.md index 7367396df6..87b6fa9e51 100644 --- a/packages/labs/compiler/README.md +++ b/packages/labs/compiler/README.md @@ -1,6 +1,93 @@ # @lit-labs/compiler -> **Warning** -> Work in progress, not ready for external use. +A compiler for optimizing Lit templates. -Tracking RFC: https://github.com/lit/rfcs/pull/21 +> **Warning** > `@lit-labs/compiler` is part of the Lit Labs set of packages – it is published +> in order to get feedback on the design and may receive breaking changes. +> Tracking RFC: https://github.com/lit/rfcs/pull/21 + +> **Warning** > `@lit-labs/compiler` is not yet published so it cannot be installed from npm. + +## Overview + +`@lit-labs/compiler` exports a [TypeScript +Transformer](https://github.com/itsdouges/typescript-transformer-handbook#types-of-transformers) +that can be run over your JavaScript or TypeScript files to optimize away the +`lit-html` **prepare** render phase. + +## Usage + +This transformer can be used anywhere TypeScript transformers are accepted, which changes based on your build setup. + +Below is an example using [Rollup](https://rollupjs.org/), and the plugin [`@rollup/plugin-typescript`](https://www.npmjs.com/package/@rollup/plugin-typescript): + +```js +// File: rollup.config.js +import typescript from '@rollup/plugin-typescript'; +import {compileLitTemplates} from './lib/template-transform.js'; + +export default { + // ... `input` and `output` configuration is specific to your project. + plugins: [ + typescript({ + transformers: { + before: [compileLitTemplates()], + }, + }), + // Other rollup plugins + ], +}; +``` + +This is based on a real rollup config used to test that source-maps are preserved after compilation in the lit repo [here](https://github.com/lit/lit/blob/main/packages/labs/compiler/rollup.source_map_tests.js). + +# FAQ + +## What are the tradeoffs for using the compiler? + +1. Running the compiler requires a build step that can accept a TypeScript transformer. + +2. The very first template render is faster (sometimes up to 45% faster for template heavy sites), but it currently comes with a 5% output file size increase (gzipped). + +## How do I know optimizations have been applied? + +Given your original source code containing the `html` tag function to declare templates: + +```js +const hi = (name) => html`

Hello ${name}!

`; +``` + +This code should have been emitted at the end of your build without the `html` tag function. +E.g. the above authored example is transformed into something like: + +```js +const b = (s) => s; +const lit_template_1 = {h: b`

Hello

`, parts: [{type: 2, index: 1}]}; +const hi = (name) => ({_$litType$: lit_template_1, values: [name]}); +``` + +## What templates are optimized by the compiler? + +In order for a template to be optimized by the compiler, it must be: + +1. A well-formed template that wouldn't raise runtime diagnostics. For example, templates with expressions in [invalid locations](https://lit.dev/docs/templates/expressions/#invalid-locations) will not be compiled. +1. Use `html` imported directly from the module `lit` or `lit-html`. The following imports are supported: + 1. `import {html} from 'lit';` Usage: `` html`...` `` + 1. `import {html as litHtml} from 'lit';` Usage: `` litHtml`...` `` + 1. `import * as litModule from 'lit'` Usage: `` litModule.html`...` `` +1. Cannot contain dynamic bindings within the raw text elements: `textarea`, `title`, `style`, and `script`. This is due to these elements containing raw text nodes as children & the limitation that raw text nodes cannot be placed as adjacent children in HTML markup. + +## Does the compiler work on JavaScript files? + +Because JavaScript is a subset of TypeScript, the TypeScript transform has been implemented and tested such that it handles JavaScript. + +You will need to run the compiler transformer over your JavaScript files. + +# Future work + +- Investigate if it's possible to reduce the file size increase on the compilers + output. +- Expand compilation so the complete optimization of a lit application can also + tree-shake the relevant `lit-html` runtime that is no longer needed. +- Explore more optimizations than just the prepare phase. +- Provide different ways of consuming and using the compiler. From 202b6a588e92c1219a79dad27f00ba6bd8157ea0 Mon Sep 17 00:00:00 2001 From: Andrew Jakubowicz Date: Mon, 14 Aug 2023 17:35:15 -0700 Subject: [PATCH 2/7] add empty changeset --- .changeset/small-buckets-notice.md | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 .changeset/small-buckets-notice.md diff --git a/.changeset/small-buckets-notice.md b/.changeset/small-buckets-notice.md new file mode 100644 index 0000000000..a845151cc8 --- /dev/null +++ b/.changeset/small-buckets-notice.md @@ -0,0 +1,2 @@ +--- +--- From d43f88a3173522b61e33e05bf487e6034ac379d6 Mon Sep 17 00:00:00 2001 From: Andrew Jakubowicz Date: Mon, 14 Aug 2023 17:39:31 -0700 Subject: [PATCH 3/7] apply some wording changes --- packages/labs/compiler/README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/packages/labs/compiler/README.md b/packages/labs/compiler/README.md index 87b6fa9e51..14cbfa502e 100644 --- a/packages/labs/compiler/README.md +++ b/packages/labs/compiler/README.md @@ -2,44 +2,44 @@ A compiler for optimizing Lit templates. -> **Warning** > `@lit-labs/compiler` is part of the Lit Labs set of packages – it is published +> **Warning** `@lit-labs/compiler` is part of the Lit Labs set of packages – it is published > in order to get feedback on the design and may receive breaking changes. > Tracking RFC: https://github.com/lit/rfcs/pull/21 -> **Warning** > `@lit-labs/compiler` is not yet published so it cannot be installed from npm. +> **Warning** `@lit-labs/compiler` is not yet published so it cannot be installed from npm. ## Overview `@lit-labs/compiler` exports a [TypeScript Transformer](https://github.com/itsdouges/typescript-transformer-handbook#types-of-transformers) that can be run over your JavaScript or TypeScript files to optimize away the -`lit-html` **prepare** render phase. +`lit-html` **prepare** render phase. For template heavy applications this can result in a quicker first render. ## Usage -This transformer can be used anywhere TypeScript transformers are accepted, which changes based on your build setup. +This transformer can be used anywhere TypeScript transformers are accepted, which is dependent on your build setup. -Below is an example using [Rollup](https://rollupjs.org/), and the plugin [`@rollup/plugin-typescript`](https://www.npmjs.com/package/@rollup/plugin-typescript): +Below is an example using [Rollup](https://rollupjs.org/) with the plugin [`@rollup/plugin-typescript`](https://www.npmjs.com/package/@rollup/plugin-typescript): ```js // File: rollup.config.js import typescript from '@rollup/plugin-typescript'; -import {compileLitTemplates} from './lib/template-transform.js'; +import {compileLitTemplates} from '@lit-labs/compiler'; export default { - // ... `input` and `output` configuration is specific to your project. + // ... plugins: [ typescript({ transformers: { before: [compileLitTemplates()], }, }), - // Other rollup plugins + // other rollup plugins ], }; ``` -This is based on a real rollup config used to test that source-maps are preserved after compilation in the lit repo [here](https://github.com/lit/lit/blob/main/packages/labs/compiler/rollup.source_map_tests.js). +This is based on a rollup config used to test that source-maps are preserved after compilation in the lit repo. See [the test rollup config for a full example](https://github.com/lit/lit/blob/main/packages/labs/compiler/rollup.source_map_tests.js). # FAQ From e451a1e55894404f04974486d31c7c5f028ccb4e Mon Sep 17 00:00:00 2001 From: Andrew Jakubowicz Date: Mon, 14 Aug 2023 17:57:24 -0700 Subject: [PATCH 4/7] Update packages/labs/compiler/README.md Co-authored-by: Augustine Kim --- packages/labs/compiler/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/labs/compiler/README.md b/packages/labs/compiler/README.md index 14cbfa502e..a3533f4c14 100644 --- a/packages/labs/compiler/README.md +++ b/packages/labs/compiler/README.md @@ -11,7 +11,7 @@ A compiler for optimizing Lit templates. ## Overview `@lit-labs/compiler` exports a [TypeScript -Transformer](https://github.com/itsdouges/typescript-transformer-handbook#types-of-transformers) +Transformer](https://github.com/itsdouges/typescript-transformer-handbook#the-basics) that can be run over your JavaScript or TypeScript files to optimize away the `lit-html` **prepare** render phase. For template heavy applications this can result in a quicker first render. From 87b01a1ccdc69e311eccf033c77bc72f81aad372 Mon Sep 17 00:00:00 2001 From: Andrew Jakubowicz Date: Mon, 14 Aug 2023 18:00:00 -0700 Subject: [PATCH 5/7] Update packages/labs/compiler/README.md Co-authored-by: Augustine Kim --- packages/labs/compiler/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/labs/compiler/README.md b/packages/labs/compiler/README.md index a3533f4c14..9c90b75bcf 100644 --- a/packages/labs/compiler/README.md +++ b/packages/labs/compiler/README.md @@ -39,7 +39,7 @@ export default { }; ``` -This is based on a rollup config used to test that source-maps are preserved after compilation in the lit repo. See [the test rollup config for a full example](https://github.com/lit/lit/blob/main/packages/labs/compiler/rollup.source_map_tests.js). +See an example of the transformer in use in this project's test for source-maps validity in this [rollup config file](https://github.com/lit/lit/blob/main/packages/labs/compiler/rollup.source_map_tests.js). # FAQ From a28c2f4f4780463ce7ce784a4122c7d05f5828f6 Mon Sep 17 00:00:00 2001 From: Andrew Jakubowicz Date: Mon, 14 Aug 2023 18:12:08 -0700 Subject: [PATCH 6/7] Update packages/labs/compiler/README.md Co-authored-by: Justin Fagnani --- packages/labs/compiler/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/labs/compiler/README.md b/packages/labs/compiler/README.md index 9c90b75bcf..fc56c1b7cb 100644 --- a/packages/labs/compiler/README.md +++ b/packages/labs/compiler/README.md @@ -70,7 +70,7 @@ const hi = (name) => ({_$litType$: lit_template_1, values: [name]}); In order for a template to be optimized by the compiler, it must be: -1. A well-formed template that wouldn't raise runtime diagnostics. For example, templates with expressions in [invalid locations](https://lit.dev/docs/templates/expressions/#invalid-locations) will not be compiled. +1. A well-formed template that wouldn't raise runtime diagnostics in development builds of lit-html. For example, templates with expressions in [invalid locations](https://lit.dev/docs/templates/expressions/#invalid-locations) will not be compiled. 1. Use `html` imported directly from the module `lit` or `lit-html`. The following imports are supported: 1. `import {html} from 'lit';` Usage: `` html`...` `` 1. `import {html as litHtml} from 'lit';` Usage: `` litHtml`...` `` From f96446963354959e05f7e1b00f424600ad0dbca6 Mon Sep 17 00:00:00 2001 From: Andrew Jakubowicz Date: Mon, 14 Aug 2023 18:17:25 -0700 Subject: [PATCH 7/7] code review feedback --- packages/labs/compiler/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/labs/compiler/README.md b/packages/labs/compiler/README.md index fc56c1b7cb..87fa33d3b4 100644 --- a/packages/labs/compiler/README.md +++ b/packages/labs/compiler/README.md @@ -13,7 +13,7 @@ A compiler for optimizing Lit templates. `@lit-labs/compiler` exports a [TypeScript Transformer](https://github.com/itsdouges/typescript-transformer-handbook#the-basics) that can be run over your JavaScript or TypeScript files to optimize away the -`lit-html` **prepare** render phase. For template heavy applications this can result in a quicker first render. +[`lit-html` **prepare** render phase](https://github.com/lit/lit/blob/main/dev-docs/design/how-lit-html-works.md#rendering). For template heavy applications this can result in a quicker first render. ## Usage @@ -47,7 +47,7 @@ See an example of the transformer in use in this project's test for source-maps 1. Running the compiler requires a build step that can accept a TypeScript transformer. -2. The very first template render is faster (sometimes up to 45% faster for template heavy sites), but it currently comes with a 5% output file size increase (gzipped). +2. The very first template render is faster (sometimes up to 45% faster for template heavy pages), but currently the output file is about 5% larger (gzipped). ## How do I know optimizations have been applied? @@ -71,7 +71,7 @@ const hi = (name) => ({_$litType$: lit_template_1, values: [name]}); In order for a template to be optimized by the compiler, it must be: 1. A well-formed template that wouldn't raise runtime diagnostics in development builds of lit-html. For example, templates with expressions in [invalid locations](https://lit.dev/docs/templates/expressions/#invalid-locations) will not be compiled. -1. Use `html` imported directly from the module `lit` or `lit-html`. The following imports are supported: +1. Use `html` imported directly from the module `lit` or `lit-html`. Re-exports of `html` from other modules are not supported. The following imports are supported: 1. `import {html} from 'lit';` Usage: `` html`...` `` 1. `import {html as litHtml} from 'lit';` Usage: `` litHtml`...` `` 1. `import * as litModule from 'lit'` Usage: `` litModule.html`...` ``