feat(config): set new defaults for transformAliasedImportPaths (#4418)

this commit updates the default values for the
`transformAliasedImportPaths` and
`transformAliasedImportPathsInCollection` configuration fields. both are
being updated to be set to `true` if neither a `true` nor `false` value
is provided (previously `false` if `false` or nothing was provided).

the latter of the two is used to set the former for, hence its new
default.

by setting both of these new defaults to `true`, the hope is that
stencil configuration will be simplified for projects using `paths` in
their `tsconfig.json`

STENCIL-829

BREAKING CHANGE: `transformAliasedImportPaths` and `transformAliasedPathsInCollection` both default to `true`. To opt-out of these new defaults, both may be set to `false` in `stencil.config.ts`. See https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#transformaliasedimportpaths and https://stenciljs.com/docs/introduction/upgrading-to-stencil-four#transformaliasedimportpathsincollection (respectively) for more information

BREAKING_CHANGES.md

@@ -12,6 +12,9 @@ This is a comprehensive list of the breaking changes introduced in the major ver
 ## Stencil v4.0.0
 
 - [General](#general)
+  - [New Configuration Defaults](#new-configuration-defaults)
+    - [transformAliasedImportPaths](#transformaliasedimportpaths)
+    - [transformAliasedImportPathsInCollection](#transformaliasedimportpathsincollection)
   - [In Browser Compilation Support Removed](#in-browser-compilation-support-removed)
   - [Legacy Context and Connect APIs Removed](#legacy-context-and-connect-APIs-removed)
   - [Legacy Browser Support Removed](#legacy-browser-support-removed)
@@ -21,6 +24,82 @@ This is a comprehensive list of the breaking changes introduced in the major ver
 
 ### General
 
+#### New Configuration Defaults
+Starting with Stencil v4.0.0, the default configuration values have changed for a few configuration options.
+The following sections lay out the configuration options that have changed, their new default values, and ways to opt-out of the new behavior (if applicable).
+
+##### `transformAliasedImportPaths`
+
+TypeScript projects have the ability to specify a path aliases via the [`paths` configuration in their `tsconfig.json`](https://www.typescriptlang.org/docs/handbook/module-resolution.html#path-mapping) like so:
+```json title="tsconfig.json"
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@utils": ["src/utils/index.ts"]
+    }
+  }
+}
+```
+In the example above, `"@utils"` would be mapped to the string `"src/utils/index.ts"` when TypeScript performs type resolution.
+The TypeScript compiler does not however, transform these paths from their keys to their values as a part of its output.
+Instead, it relies on a bundler/loader to do the transformation.
+
+The ability to transform path aliases was introduced in [Stencil v3.1.0](https://github.com/ionic-team/stencil/releases/tag/v3.1.0) as an opt-in feature.
+Previously, users had to explicitly enable this functionality in their `stencil.config.ts` file with `transformAliasedImportPaths`:
+```ts title="stencil.config.ts - enabling 'transformAliasedImportPaths' in Stencil v3.1.0"
+import { Config } from '@stencil/core';
+
+export const config: Config = {
+  transformAliasedImportPaths: true,
+  // ...
+};
+```
+
+Starting with Stencil v4.0.0, this feature is enabled by default.
+Projects that had previously enabled this functionality that are migrating from Stencil v3.1.0+ may safely remove the flag from their Stencil configuration file(s).
+
+For users that run into issues with this new default, we encourage you to file a [new issue on the Stencil GitHub repo](https://github.com/ionic-team/stencil/issues/new?assignees=&labels=&projects=&template=bug_report.yml&title=bug%3A+).
+As a workaround, this flag can be set to `false` to disable the default functionality.
+```ts title="stencil.config.ts - disabling 'transformAliasedImportPaths' in Stencil v4.0.0"
+import { Config } from '@stencil/core';
+
+export const config: Config = {
+  transformAliasedImportPaths: false,
+  // ...
+};
+```
+
+For more information on this flag, please see the [configuration documentation](https://stenciljs.com/docs/config#transformaliasedimportpaths)
+
+##### `transformAliasedImportPathsInCollection`
+
+Introduced in [Stencil v2.18.0](https://github.com/ionic-team/stencil/releases/tag/v2.18.0), `transformAliasedImportPathsInCollection` is a configuration flag on the [`dist` output target](https://stenciljs.com/docs/distribution#transformaliasedimportpathsincollection).
+`transformAliasedImportPathsInCollection` transforms import paths, similar to [`transformAliasedImportPaths`](#transformaliasedimportpathsincollection).
+This flag however, only enables the functionality of `transformAliasedImportPaths` for collection output targets.
+
+Starting with Stencil v4.0.0, this flag is enabled by default.
+Projects that had previously enabled this functionality that are migrating from Stencil v2.18.0+ may safely remove the flag from their Stencil configuration file(s).
+
+For users that run into issues with this new default, we encourage you to file a [new issue on the Stencil GitHub repo](https://github.com/ionic-team/stencil/issues/new?assignees=&labels=&projects=&template=bug_report.yml&title=bug%3A+).
+As a workaround, this flag can be set to `false` to disable the default functionality.
+```ts title="stencil.config.ts - disabling 'transformAliasedImportPathsInCollection' in Stencil v4.0.0"
+import { Config } from '@stencil/core';
+
+export const config: Config = {
+  outputTargets: [
+    {
+      type: 'dist',
+      transformAliasedImportPathsInCollection: false,
+    },
+    // ...
+  ]
+  // ...
+};
+```
+
+For more information on this flag, please see the [`dist` output target's documentation](https://stenciljs.com/docs/distribution#transformaliasedimportpathsincollection).
+
 #### In Browser Compilation Support Removed
 
 Prior to Stencil v4.0.0, components could be compiled from TSX to JS in the browser.

src/compiler/config/outputs/validate-collection.ts

@@ -1,4 +1,4 @@
-import { isOutputTargetDistCollection } from '@utils';
+import { isBoolean, isOutputTargetDistCollection } from '@utils';
 
 import type * as d from '../../../declarations';
 import { getAbsolutePath } from '../config-utils';
@@ -18,7 +18,9 @@ export const validateCollection = (
   return userOutputs.filter(isOutputTargetDistCollection).map((outputTarget) => {
     return {
       ...outputTarget,
-      transformAliasedImportPaths: outputTarget.transformAliasedImportPaths ?? false,
+      transformAliasedImportPaths: isBoolean(outputTarget.transformAliasedImportPaths)
+        ? outputTarget.transformAliasedImportPaths
+        : true,
       dir: getAbsolutePath(config, outputTarget.dir ?? 'dist/collection'),
     };
   });

src/compiler/config/outputs/validate-dist.ts

@@ -137,7 +137,9 @@ const validateOutputTargetDist = (config: d.ValidatedConfig, o: d.OutputTargetDi
     copy: validateCopy(o.copy ?? [], []),
     polyfills: isBoolean(o.polyfills) ? o.polyfills : undefined,
     empty: isBoolean(o.empty) ? o.empty : true,
-    transformAliasedImportPathsInCollection: o.transformAliasedImportPathsInCollection ?? false,
+    transformAliasedImportPathsInCollection: isBoolean(o.transformAliasedImportPathsInCollection)
+      ? o.transformAliasedImportPathsInCollection
+      : true,
     isPrimaryPackageOutputTarget: o.isPrimaryPackageOutputTarget ?? false,
   };
 

src/compiler/config/test/validate-config.spec.ts

@@ -110,9 +110,9 @@ describe('validation', () => {
       expect(config.transformAliasedImportPaths).toBe(bool);
     });
 
-    it('default transformAliasedImportPaths false', () => {
+    it('defaults `transformAliasedImportPaths` to true', () => {
       const { config } = validateConfig(userConfig, bootstrapConfig);
-      expect(config.transformAliasedImportPaths).toBe(false);
+      expect(config.transformAliasedImportPaths).toBe(true);
     });
   });
 

src/compiler/config/test/validate-output-dist-collection.spec.ts

@@ -31,7 +31,7 @@ describe('validateDistCollectionOutputTarget', () => {
         empty: false,
         dir: defaultDir,
         collectionDir: null,
-        transformAliasedImportPaths: false,
+        transformAliasedImportPaths: true,
       },
     ]);
   });
@@ -53,7 +53,7 @@ describe('validateDistCollectionOutputTarget', () => {
         empty: false,
         dir: '/my-dist',
         collectionDir: null,
-        transformAliasedImportPaths: false,
+        transformAliasedImportPaths: true,
       },
     ]);
   });

src/compiler/config/test/validate-output-dist.spec.ts

@@ -33,7 +33,7 @@ describe('validateDistOutputTarget', () => {
         type: 'dist',
         polyfills: undefined,
         typesDir: path.join(rootDir, 'my-dist', 'types'),
-        transformAliasedImportPathsInCollection: false,
+        transformAliasedImportPathsInCollection: true,
         isPrimaryPackageOutputTarget: false,
       },
       {
@@ -65,7 +65,7 @@ describe('validateDistOutputTarget', () => {
         collectionDir: path.join(rootDir, 'my-dist', 'collection'),
         dir: path.join(rootDir, '/my-dist'),
         empty: false,
-        transformAliasedImportPaths: false,
+        transformAliasedImportPaths: true,
         type: 'dist-collection',
       },
       {
@@ -223,7 +223,7 @@ describe('validateDistOutputTarget', () => {
         type: 'dist',
         polyfills: undefined,
         typesDir: path.join(rootDir, 'my-dist', 'types'),
-        transformAliasedImportPathsInCollection: false,
+        transformAliasedImportPathsInCollection: true,
         isPrimaryPackageOutputTarget: true,
       },
       {
@@ -255,7 +255,7 @@ describe('validateDistOutputTarget', () => {
         collectionDir: path.join(rootDir, 'my-dist', 'collection'),
         dir: path.join(rootDir, '/my-dist'),
         empty: false,
-        transformAliasedImportPaths: false,
+        transformAliasedImportPaths: true,
         type: 'dist-collection',
       },
       {

src/compiler/config/test/validate-service-worker.spec.ts

@@ -22,7 +22,7 @@ describe('validateServiceWorker', () => {
       rootDir: '/',
       sys: mockCompilerSystem(),
       testing: {},
-      transformAliasedImportPaths: false,
+      transformAliasedImportPaths: true,
     });
   });
 

src/compiler/config/validate-config.ts

@@ -87,7 +87,9 @@ export const validateConfig = (
     rollupConfig: validateRollupConfig(config),
     sys: config.sys ?? bootstrapConfig.sys ?? createNodeSys({ logger }),
     testing: config.testing ?? {},
-    transformAliasedImportPaths: userConfig.transformAliasedImportPaths ?? false,
+    transformAliasedImportPaths: isBoolean(userConfig.transformAliasedImportPaths)
+      ? userConfig.transformAliasedImportPaths
+      : true,
     validatePrimaryPackageOutputTarget: userConfig.validatePrimaryPackageOutputTarget ?? false,
     ...validatePaths(config),
   };

src/compiler/output-targets/test/output-targets-collection.spec.ts

@@ -47,7 +47,7 @@ describe('Dist Collection output target', () => {
 
   describe('transform aliased import paths', () => {
     // These tests ensure that the transformer for import paths is called regardless
-    // of the config value (the function will decided whether or not to actually do anything) to avoid
+    // of the config value (the function will decide whether or not to actually do anything) to avoid
     // a race condition with duplicate file writes
     it.each([true, false])(
       'calls function to transform aliased import paths when the output target config flag is `%s`',

src/declarations/stencil-public-compiler.ts

@@ -139,7 +139,7 @@ export interface StencilConfig {
    * Sets whether or not Stencil should transform path aliases set in a project's
    * `tsconfig.json` from the assigned module aliases to resolved relative paths.
    *
-   * This behavior is opt-in and hence this flag defaults to `false`.
+   * This behavior defaults to `true`, but may be opted-out of by setting this flag to `false`.
    */
   transformAliasedImportPaths?: boolean;
   /**
@@ -1940,7 +1940,7 @@ export interface OutputTargetDist extends OutputTargetValidationConfig {
    * a project's `tsconfig.json` to relative import paths in the compiled output's
    * `dist-collection` bundle if it is generated (i.e. `collectionDir` is set).
    *
-   * Paths will be left in aliased format if `false` or `undefined`.
+   * Paths will be left in aliased format if `false`.
    *
    * @example
    * // tsconfig.json

src/testing/mocks.ts

@@ -46,7 +46,7 @@ export function mockValidatedConfig(overrides: Partial<ValidatedConfig> = {}): V
     srcDir: '/src',
     sys: createTestingSystem(),
     testing: {},
-    transformAliasedImportPaths: false,
+    transformAliasedImportPaths: true,
     rollupConfig: {
       inputOptions: {},
       outputOptions: {},

test/karma/test-sibling/stencil.config.ts

@@ -6,6 +6,7 @@ export const config: Config = {
   outputTargets: [
     {
       type: 'dist',
+      transformAliasedImportPathsInCollection: false,
     },
   ],
   globalScript: 'src/global.ts',