From 365dd1cc678d19190100f5eea87616c9a0332652 Mon Sep 17 00:00:00 2001 From: Nolan Lawson Date: Wed, 22 Mar 2023 16:11:45 -0700 Subject: [PATCH 1/3] docs: document options for @lwc/compiler and @lwc/babel-plugin-component --- .../@lwc/babel-plugin-component/README.md | 37 +++++++++++++++++++ packages/@lwc/compiler/README.md | 32 +++++++++++++--- 2 files changed, 64 insertions(+), 5 deletions(-) diff --git a/packages/@lwc/babel-plugin-component/README.md b/packages/@lwc/babel-plugin-component/README.md index 196f257e4a..92e320271b 100644 --- a/packages/@lwc/babel-plugin-component/README.md +++ b/packages/@lwc/babel-plugin-component/README.md @@ -1,5 +1,7 @@ # @lwc/babel-plugin-component +## Summary + This babel plugin does the following transform: - Global decorator transform: @@ -11,3 +13,38 @@ This babel plugin does the following transform: - Import and inject `render` from a collocated template if a component class doesn't already implement a `render` method. - Optimization: - If the compiler inject the default template a component, it will also wire the template style to the component. + +## Installation + + npm install babel @lwc/babel-plugin-component + +## Usage + +```js +const babel = require('@babel/core'); +const lwcPlugin = require('@lwc/babel-plugin-component'); + +const source = ` +import { LightningElement } from 'lwc'; +export default class extends LightningElement {}`; + +const { code } = babel.transformSync(source, { + plugins: [ + [ + lwcPlugin, + { + /* options */ + }, + ], + ], +}); +``` + +## Options + +- `name` (type: `string`, optional) - name of the component, e.g. `foo` in `x/foo` +- `namespace` (type: `string`, optional) - namepace of the component, e.g. `x` in `x/foo` +- `isExplicitImport` (type: `boolean`, optional) - true if this is an explicit import. +- `dynamicImporta` (type: `object`, optional) - see below: + - `loader` (type: `string`, optional) - loader to use at runtime. + - `strictSpecifier` (type: `boolean`, optional) - true if a strict specifier should be used. diff --git a/packages/@lwc/compiler/README.md b/packages/@lwc/compiler/README.md index f10511e849..86ea38ccdd 100644 --- a/packages/@lwc/compiler/README.md +++ b/packages/@lwc/compiler/README.md @@ -1,21 +1,23 @@ # LWC Compiler +## Summary + @lwc/compiler is an open source project that enables developers to take full control of processing a single Lightning Web Components module for runtime consumption. ## Installation ```sh -yarn add --dev @lwc/compiler +npm install @lwc/compiler ``` ## APIs -### `transform` +### `transformSync` Transform the content of individual file. ```js -import { transform } from '@lwc/compiler'; +import { transformSync } from '@lwc/compiler'; const source = ` import { LightningElement } from 'lwc'; @@ -29,14 +31,30 @@ const options = { name: 'app', }; -const { code } = await transform(source, filename, options); +const { code } = transformSync(source, filename, options); ``` **Parameters:** -- `source` (string, required) - the source to be transformed can be the content of javascript, HTML, CSS. +- `source` (string, required) - the source to be transformed. Can be the content of a JavaScript, HTML, or CSS file. - `filename` (string, required) - the source filename with extension. - `options` (object, required) - the transformation options. The `name` and the `namespace` of the component is a minimum required for transformation. + - `name` (type: `string`, required) - name of the component, e.g. `foo` in `x/foo` + - `namespace` (type: `string`, required) - namespace of the component, e.g. `x` in `x/foo` + - `stylesheetConfig` (type: `object`, default: `{}`) - The stylesheet compiler configuration to pass to the `@lwc/style-compiler`. + - `experimentalDynamicComponent` (type: `DynamicImportConfig`, default: `null`) - The configuration to pass to `@lwc/compiler`. + - `experimentalDynamicDirective` (type: `boolean`, default: `false`) - The configuration to pass to `@lwc/template-compiler` to enable deprecated dynamic components. + - `enableDynamicComponents` (type: `boolean`, default: `false`) - The configuration to pass to `@lwc/template-compiler` to enable dynamic components. + - `outputConfig` (type: `object`, optional) - see below: + - `sourcemap` (type: `boolean`, optional) - if `true`, a sourcemap is generated for the transformed file. + - `minify` (type: `boolean`, optional, deprecated) - this option has no effect. + - `isExplicitImport` (type: `boolean`, optional) - true if this is an explicit import, passed to `@lwc/babel-plugin-component`. + - `preserveHtmlComments` (type: `boolean`, default: `false`) - The configuration to pass to the `@lwc/template-compiler`. + - `scopedStyles` (type: `boolean`, optional) - True if the CSS file being compiled is a scoped stylesheet. Passed to `@lwc/style-compiler`. + - `enableStaticContentOptimization` (type: `boolean`, optional) - True if the static content optimization should be enabled. Passed to `@lwc/template-compiler`. + - `customRendererConfig` (type: `object`, optional) - custom renderer config to pass to `@lwc/template-compiler`. See that package's README for details. + - `enableLwcSpread` (type: `boolean`, default: `false`) - The configuration to pass to the `@lwc/template-compiler`. + - `disableSyntheticShadowSupport` (type: `boolean`, default: `false`) - Set to true if synthetic shadow DOM support is not needed, which can result in smaller output. **Return** @@ -44,6 +62,10 @@ const { code } = await transform(source, filename, options); - `map` (object) - the generated source map. - `warnings` (array, optional) - the array of diagnostic warnings, if any. +### `transform` (deprecated) + +Deprecated asynchronous equivalent of `transformSync`. + ### `version` ```js From e497d5386f0ac882f44c64ca49d18564b0f38abc Mon Sep 17 00:00:00 2001 From: Nolan Lawson Date: Wed, 22 Mar 2023 16:15:11 -0700 Subject: [PATCH 2/3] fix: punct and spacing --- packages/@lwc/babel-plugin-component/README.md | 4 ++-- packages/@lwc/compiler/README.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/@lwc/babel-plugin-component/README.md b/packages/@lwc/babel-plugin-component/README.md index 92e320271b..70449ae702 100644 --- a/packages/@lwc/babel-plugin-component/README.md +++ b/packages/@lwc/babel-plugin-component/README.md @@ -42,8 +42,8 @@ const { code } = babel.transformSync(source, { ## Options -- `name` (type: `string`, optional) - name of the component, e.g. `foo` in `x/foo` -- `namespace` (type: `string`, optional) - namepace of the component, e.g. `x` in `x/foo` +- `name` (type: `string`, optional) - name of the component, e.g. `foo` in `x/foo`. +- `namespace` (type: `string`, optional) - namepace of the component, e.g. `x` in `x/foo`. - `isExplicitImport` (type: `boolean`, optional) - true if this is an explicit import. - `dynamicImporta` (type: `object`, optional) - see below: - `loader` (type: `string`, optional) - loader to use at runtime. diff --git a/packages/@lwc/compiler/README.md b/packages/@lwc/compiler/README.md index 86ea38ccdd..aad3b5e7da 100644 --- a/packages/@lwc/compiler/README.md +++ b/packages/@lwc/compiler/README.md @@ -39,8 +39,8 @@ const { code } = transformSync(source, filename, options); - `source` (string, required) - the source to be transformed. Can be the content of a JavaScript, HTML, or CSS file. - `filename` (string, required) - the source filename with extension. - `options` (object, required) - the transformation options. The `name` and the `namespace` of the component is a minimum required for transformation. - - `name` (type: `string`, required) - name of the component, e.g. `foo` in `x/foo` - - `namespace` (type: `string`, required) - namespace of the component, e.g. `x` in `x/foo` + - `name` (type: `string`, required) - name of the component, e.g. `foo` in `x/foo`. + - `namespace` (type: `string`, required) - namespace of the component, e.g. `x` in `x/foo`. - `stylesheetConfig` (type: `object`, default: `{}`) - The stylesheet compiler configuration to pass to the `@lwc/style-compiler`. - `experimentalDynamicComponent` (type: `DynamicImportConfig`, default: `null`) - The configuration to pass to `@lwc/compiler`. - `experimentalDynamicDirective` (type: `boolean`, default: `false`) - The configuration to pass to `@lwc/template-compiler` to enable deprecated dynamic components. From ef8a0427207ade46a458c9fefb043b3c3f6e9e9b Mon Sep 17 00:00:00 2001 From: Nolan Lawson Date: Thu, 30 Mar 2023 15:09:10 -0700 Subject: [PATCH 3/3] fix: document experimentalComplexExpressions --- packages/@lwc/compiler/README.md | 1 + packages/@lwc/template-compiler/README.md | 1 + 2 files changed, 2 insertions(+) diff --git a/packages/@lwc/compiler/README.md b/packages/@lwc/compiler/README.md index aad3b5e7da..3aa0627437 100644 --- a/packages/@lwc/compiler/README.md +++ b/packages/@lwc/compiler/README.md @@ -48,6 +48,7 @@ const { code } = transformSync(source, filename, options); - `outputConfig` (type: `object`, optional) - see below: - `sourcemap` (type: `boolean`, optional) - if `true`, a sourcemap is generated for the transformed file. - `minify` (type: `boolean`, optional, deprecated) - this option has no effect. + - `experimentalComplexExpressions` (type: `boolean`, optional) - set to true to enable use of (a subset of) JavaScript expressions in place of template bindings. Passed to `@lwc/template-compiler`. - `isExplicitImport` (type: `boolean`, optional) - true if this is an explicit import, passed to `@lwc/babel-plugin-component`. - `preserveHtmlComments` (type: `boolean`, default: `false`) - The configuration to pass to the `@lwc/template-compiler`. - `scopedStyles` (type: `boolean`, optional) - True if the CSS file being compiled is a scoped stylesheet. Passed to `@lwc/style-compiler`. diff --git a/packages/@lwc/template-compiler/README.md b/packages/@lwc/template-compiler/README.md index 06899658e3..3e7b6d14af 100644 --- a/packages/@lwc/template-compiler/README.md +++ b/packages/@lwc/template-compiler/README.md @@ -49,6 +49,7 @@ const { code, warnings } = compile(``, **Options:** - `experimentalComputedMemberExpression` (boolean, optional, `false` by default) - set to `true` to enable computed member expression in the template, eg: `{list[0].name}`. +- `experimentalComplexExpressions` (boolean, optional, `false` by default) - set to `true` to enable use of (a subset of) JavaScript expressions in place of template bindings. - `experimentalDynamicDirective` (boolean, optional, `false` by default) - set to `true` to allow the usage of `lwc:dynamic` directives in the template. - `enableDynamicComponents` (boolean, optional, `false` by default) - set to `true` to enable `lwc:is` directive in the template. - `preserveHtmlComments` (boolean, optional, `false` by default) - set to `true` to disable the default behavior of stripping HTML comments.