v6.3.0

.eslintrc

@@ -146,8 +146,6 @@
         /*
          * TODO: Address violations and re-enable these rules
          */
-        // All @ts-ignore should either be refactored or changed to @ts-expect-error <reason>
-        "@typescript-eslint/ban-ts-comment": "off",
         // Enums are a pain to deal with...
         "@typescript-eslint/no-unsafe-enum-comparison": "off",
         // We might just want to leave this one disabled
@@ -306,20 +304,19 @@
         },
         {
             "files": [
-                "packages/lwc/**",
                 // Private packages - documentation isn't required (but should still be good, if present)
                 "packages/@lwc/integration-karma/**",
                 "packages/@lwc/integration-tests/**",
                 "packages/@lwc/perf-benchmarks-components/**",
                 "packages/@lwc/perf-benchmarks/**",
                 // TODO [W-13278716]: All top-level exports should have JSDOC enforced
-                "packages/@lwc/compiler/**",
                 "packages/@lwc/engine-core/**",
-                "packages/@lwc/engine-dom/**",
-                "packages/@lwc/engine-server/**",
+                // "packages/@lwc/engine-server/**",
                 // Package-level exports are documented, but not all file-level exports are, so we
                 // should keep these disabled for now
                 "packages/@lwc/babel-plugin-component/**",
+                "packages/@lwc/engine-dom/**",
+                "packages/@lwc/engine-server/**",
                 "packages/@lwc/module-resolver/**",
                 "packages/@lwc/shared/**",
                 "packages/@lwc/style-compiler/**",
@@ -341,7 +338,9 @@
         {
             "files": [
                 "packages/@lwc/babel-plugin-component/**",
+                "packages/@lwc/compiler/**",
                 "packages/@lwc/errors/**",
+                "packages/@lwc/engine-dom/**",
                 "packages/@lwc/rollup-plugin/**",
                 "packages/@lwc/wire-service/**"
             ],

package.json

@@ -1,6 +1,6 @@
 {
     "name": "lwc-monorepo",
-    "version": "6.2.1",
+    "version": "6.3.0",
     "private": true,
     "description": "Lightning Web Components",
     "repository": {

packages/@lwc/aria-reflection/package.json

@@ -4,7 +4,7 @@
         "You can safely modify dependencies, devDependencies, keywords, etc., but other props will be overwritten."
     ],
     "name": "@lwc/aria-reflection",
-    "version": "6.2.1",
+    "version": "6.3.0",
     "description": "ARIA element reflection polyfill for strings",
     "keywords": [
         "aom",

packages/@lwc/babel-plugin-component/package.json

@@ -4,7 +4,7 @@
         "You can safely modify dependencies, devDependencies, keywords, etc., but other props will be overwritten."
     ],
     "name": "@lwc/babel-plugin-component",
-    "version": "6.2.1",
+    "version": "6.3.0",
     "description": "Babel plugin to transform a LWC module",
     "keywords": [
         "lwc"
@@ -43,8 +43,8 @@
     },
     "dependencies": {
         "@babel/helper-module-imports": "7.22.15",
-        "@lwc/errors": "6.2.1",
-        "@lwc/shared": "6.2.1",
+        "@lwc/errors": "6.3.0",
+        "@lwc/shared": "6.3.0",
         "line-column": "~1.0.2"
     },
     "devDependencies": {

packages/@lwc/compiler/README.md

@@ -46,7 +46,7 @@ const { code } = transformSync(source, filename, options);
     -   `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.
+        -   `sourcemap` (type: `boolean` | `'inline'`, optional) - if `true`, a sourcemap is generated for the transformed file. If `'inline'`, an inline sourcemap is generated and appended to 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`.

packages/@lwc/compiler/package.json

@@ -4,7 +4,7 @@
         "You can safely modify dependencies, devDependencies, keywords, etc., but other props will be overwritten."
     ],
     "name": "@lwc/compiler",
-    "version": "6.2.1",
+    "version": "6.3.0",
     "description": "LWC compiler",
     "keywords": [
         "lwc"
@@ -48,10 +48,10 @@
         "@babel/plugin-proposal-object-rest-spread": "7.20.7",
         "@babel/plugin-transform-async-to-generator": "7.23.3",
         "@locker/babel-plugin-transform-unforgeables": "0.20.0",
-        "@lwc/babel-plugin-component": "6.2.1",
-        "@lwc/errors": "6.2.1",
-        "@lwc/shared": "6.2.1",
-        "@lwc/style-compiler": "6.2.1",
-        "@lwc/template-compiler": "6.2.1"
+        "@lwc/babel-plugin-component": "6.3.0",
+        "@lwc/errors": "6.3.0",
+        "@lwc/shared": "6.3.0",
+        "@lwc/style-compiler": "6.3.0",
+        "@lwc/template-compiler": "6.3.0"
     }
 }

packages/@lwc/compiler/src/index.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, salesforce.com, inc.
+ * Copyright (c) 2024, Salesforce, Inc.
  * All rights reserved.
  * SPDX-License-Identifier: MIT
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
@@ -15,4 +15,5 @@ export {
     OutputConfig,
 } from './options';
 
-export const version = process.env.LWC_VERSION as string;
+/** The version of LWC being used. */
+export const version = process.env.LWC_VERSION!;

packages/@lwc/compiler/src/options.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, salesforce.com, inc.
+ * Copyright (c) 2024, Salesforce, Inc.
  * All rights reserved.
  * SPDX-License-Identifier: MIT
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
@@ -52,7 +52,7 @@ const DEFAULT_OUTPUT_CONFIG: Required<OutputConfig> = {
 export type CustomPropertiesResolution = { type: 'native' } | { type: 'module'; name: string };
 
 /**
- * @deprecated - Custom property transforms are deprecated because IE11 and other legacy browsers are no longer supported.
+ * @deprecated Custom property transforms are deprecated because IE11 and other legacy browsers are no longer supported.
  */
 // TODO [#3266]: Remove StylesheetConfig as part of breaking change wishlist
 export interface StylesheetConfig {
@@ -64,9 +64,10 @@ export interface StylesheetConfig {
 export interface OutputConfig {
     /**
      * If `true` a source map is generated for the transformed file.
+     * If `inline`, an inline source map is generated and appended to the end of the transformed file.
      * @default false
      */
-    sourcemap?: boolean;
+    sourcemap?: boolean | 'inline';
 
     /**
      * @deprecated The minify property has no effect on the generated output.
@@ -79,29 +80,53 @@ export interface DynamicImportConfig {
     strictSpecifier?: boolean;
 }
 
+/**
+ * Options used to change the behavior of the compiler. At a minimum, `name` and `namespace` are
+ * required.
+ */
 export interface TransformOptions {
+    /** The name of the component. For example, the name in `<my-component>` is `"component"`. */
     name?: string;
+    /** The namespace of the component. For example, the namespace in `<my-component>` is `"my"`. */
     namespace?: string;
+    /** @deprecated Ignored by compiler. */
     stylesheetConfig?: StylesheetConfig;
     // TODO [#3331]: deprecate / rename this compiler option in 246
-    /* Config applied in usage of dynamic import statements in javascript */
+    /** Config applied in usage of dynamic import statements in javascript */
     experimentalDynamicComponent?: DynamicImportConfig;
-    /* Flag to enable usage of dynamic component(lwc:dynamic) directive in HTML template */
+    /** Flag to enable usage of dynamic component(lwc:dynamic) directive in HTML template */
     experimentalDynamicDirective?: boolean;
-    /* Flag to enable usage of dynamic component(lwc:is) directive in HTML template */
+    /** Flag to enable usage of dynamic component(lwc:is) directive in HTML template */
     enableDynamicComponents?: boolean;
     // TODO [#3370]: remove experimental template expression flag
+    /** Flag to enable use of (a subset of) JavaScript expressions in place of template bindings. Passed to `@lwc/template-compiler`. */
     experimentalComplexExpressions?: boolean;
+    /** Options to control what output gets generated. */
     outputConfig?: OutputConfig;
+    /** Whether this is an explicit import. Passed to `@lwc/babel-plugin-component`. */
     isExplicitImport?: boolean;
+    /** Whether the compiled HTML should include comments present in the source. */
     preserveHtmlComments?: boolean;
+    /** Whether the CSS file being compiled is a scoped stylesheet. Passed to `@lwc/style-compiler`. */
     scopedStyles?: boolean;
+    /** Whether the static content optimization should be enabled. Passed to `@lwc/template-compiler`. */
     enableStaticContentOptimization?: boolean;
+    /** Custom renderer config to pass to `@lwc/template-compiler`. See that package's README for details. */
     customRendererConfig?: CustomRendererConfig;
+    /** @deprecated Ignored by compiler. `lwc:spread` is always enabled. */
     enableLwcSpread?: boolean;
+    /** Set to true if synthetic shadow DOM support is not needed, which can result in smaller output. */
     disableSyntheticShadowSupport?: boolean;
+    /**
+     * Enable transformations specific to {@link https://developer.salesforce.com/docs/platform/lwc/guide/security-lwsec-intro.html Lighting Web Security}.
+     */
     enableLightningWebSecurityTransforms?: boolean;
+    /**
+     * Instrumentation object to gather metrics and non-error logs for internal use.
+     * See the `@lwc/errors` package for details on the interface.
+     */
     instrumentation?: InstrumentationObject;
+    /** API version to associate with the compiled module. Values correspond to Salesforce platform releases. */
     apiVersion?: number;
 }
 
@@ -131,6 +156,16 @@ export interface NormalizedTransformOptions extends RecursiveRequired<RequiredTr
     instrumentation?: InstrumentationObject;
 }
 
+/**
+ * Validates that the options conform to the expected shape and normalizes them to a standard format
+ * @param options Input options
+ * @returns Normalized options
+ * @example
+ * const normalizedOptions = validateTransformOptions({
+ *   namespace: 'c',
+ *   name: 'app',
+ * })
+ */
 export function validateTransformOptions(options: TransformOptions): NormalizedTransformOptions {
     validateOptions(options);
     return normalizeOptions(options);
@@ -168,7 +203,7 @@ function isUndefinedOrBoolean(property: any): boolean {
 
 function validateOutputConfig(config: OutputConfig) {
     invariant(
-        isUndefinedOrBoolean(config.sourcemap),
+        isUndefinedOrBoolean(config.sourcemap) || config.sourcemap === 'inline',
         CompilerValidationErrors.INVALID_SOURCEMAP_PROPERTY,
         [config.sourcemap]
     );

packages/@lwc/compiler/src/transformers/__tests__/transform-javascript.spec.ts

@@ -209,3 +209,63 @@ describe('unnecessary registerDecorators', () => {
         expect(code).toContain('registerDecorators');
     });
 });
+
+describe('sourcemaps', () => {
+    it("should generate inline sourcemaps when the output config includes the 'inline' option for sourcemaps", () => {
+        const source = `
+            import { LightningElement } from 'lwc';
+            export default class Foo extends LightningElement {}
+        `;
+
+        const { code, map } = transformSync(source, 'foo.js', {
+            ...TRANSFORMATION_OPTIONS,
+            outputConfig: {
+                sourcemap: 'inline',
+            },
+        });
+        expect(code).toContain('//# sourceMappingURL=data:application/json;');
+        expect(map).toBeNull();
+    });
+
+    it("should generate sourcemaps when the sourcemap configuration value is 'true'", () => {
+        const source = `
+            import { LightningElement } from 'lwc';
+            export default class Foo extends LightningElement {}
+        `;
+
+        const { map } = transformSync(source, 'foo.js', {
+            ...TRANSFORMATION_OPTIONS,
+            outputConfig: {
+                sourcemap: true,
+            },
+        });
+        expect(map).not.toBeNull();
+    });
+
+    describe("should fail validation of options if sourcemap configuration value is neither boolean nor 'inline'.", () => {
+        const source = `
+            import { LightningElement } from 'lwc';
+            export default class Foo extends LightningElement {}
+        `;
+
+        [
+            { name: 'invalid string', sourcemap: 'invalid' },
+            { name: 'object', sourcemap: {} },
+            { name: 'numbers', sourcemap: 123 },
+        ].forEach(({ name, sourcemap }) => {
+            it(name, () => {
+                expect(() =>
+                    transformSync(source, 'foo.js', {
+                        ...TRANSFORMATION_OPTIONS,
+                        outputConfig: {
+                            // @ts-expect-error Property can be passed from JS environments with no type checking.
+                            sourcemap,
+                        },
+                    })
+                ).toThrow(
+                    `LWC1021: Expected a boolean value or 'inline' for outputConfig.sourcemap, received "${sourcemap}".`
+                );
+            });
+        });
+    });
+});

packages/@lwc/compiler/src/transformers/javascript.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, salesforce.com, inc.
+ * Copyright (c) 2024, Salesforce, Inc.
  * All rights reserved.
  * SPDX-License-Identifier: MIT
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
@@ -19,6 +19,15 @@ import { NormalizedTransformOptions } from '../options';
 import { TransformResult } from './transformer';
 import type { LwcBabelPluginOptions } from '@lwc/babel-plugin-component';
 
+/**
+ * Transforms a JavaScript file.
+ * @param code The source code to transform
+ * @param filename The source filename, with extension.
+ * @param options Transformation options.
+ * @returns Compiled code
+ * @throws Compilation errors
+ * @example
+ */
 export default function scriptTransform(
     code: string,
     filename: string,

packages/@lwc/compiler/src/transformers/style.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, salesforce.com, inc.
+ * Copyright (c) 2024, Salesforce, Inc.
  * All rights reserved.
  * SPDX-License-Identifier: MIT
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
@@ -10,6 +10,15 @@ import { normalizeToCompilerError, TransformerErrors } from '@lwc/errors';
 import { NormalizedTransformOptions } from '../options';
 import { TransformResult } from './transformer';
 
+/**
+ * Transform the passed source code
+ * @param src The source to be transformed. Can be the content of a JavaScript, HTML, or CSS file.
+ * @param filename The source filename, with extension.
+ * @param config The transformation options. The `name` and the `namespace` of the component is the
+ * minimum required for transformation.
+ * @returns An object with the generated code, source map and gathered metadata.
+ * @throws Compilation errors
+ */
 export default function styleTransform(
     src: string,
     filename: string,

packages/@lwc/compiler/src/transformers/template.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, salesforce.com, inc.
+ * Copyright (c) 2024, Salesforce, Inc.
  * All rights reserved.
  * SPDX-License-Identifier: MIT
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
@@ -21,9 +21,12 @@ import { TransformResult } from './transformer';
  * Transforms a HTML template into module exporting a template function.
  * The transform also add a style import for the default stylesheet associated with
  * the template regardless if there is an actual style or not.
- * @param src
- * @param filename
- * @param options
+ * @param src HTML source
+ * @param filename Source filename, with extension.
+ * @param options Transformation options
+ * @returns Transformed code, source map, and metadata
+ * @throws Compiler errors, when compilation fails.
+ * @example
  */
 export default function templateTransform(
     src: string,