diff --git a/BREAKING_CHANGES.md b/BREAKING_CHANGES.md index f972e1edf87..7fdf9d28b04 100644 --- a/BREAKING_CHANGES.md +++ b/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. diff --git a/src/compiler/config/outputs/validate-collection.ts b/src/compiler/config/outputs/validate-collection.ts index 87313ba7756..f3cc39c158b 100644 --- a/src/compiler/config/outputs/validate-collection.ts +++ b/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'), }; }); diff --git a/src/compiler/config/outputs/validate-dist.ts b/src/compiler/config/outputs/validate-dist.ts index 740530f1016..d95fa915f4a 100644 --- a/src/compiler/config/outputs/validate-dist.ts +++ b/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, }; diff --git a/src/compiler/config/test/validate-config.spec.ts b/src/compiler/config/test/validate-config.spec.ts index a3ef0d8971d..02629cab2cb 100644 --- a/src/compiler/config/test/validate-config.spec.ts +++ b/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); }); }); diff --git a/src/compiler/config/test/validate-output-dist-collection.spec.ts b/src/compiler/config/test/validate-output-dist-collection.spec.ts index 06911fc810d..1b2841d56b8 100644 --- a/src/compiler/config/test/validate-output-dist-collection.spec.ts +++ b/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, }, ]); }); diff --git a/src/compiler/config/test/validate-output-dist.spec.ts b/src/compiler/config/test/validate-output-dist.spec.ts index fb8df9310d6..bad32d70a59 100644 --- a/src/compiler/config/test/validate-output-dist.spec.ts +++ b/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', }, { diff --git a/src/compiler/config/test/validate-service-worker.spec.ts b/src/compiler/config/test/validate-service-worker.spec.ts index 42d1d6eaa43..66de1a68bcb 100644 --- a/src/compiler/config/test/validate-service-worker.spec.ts +++ b/src/compiler/config/test/validate-service-worker.spec.ts @@ -22,7 +22,7 @@ describe('validateServiceWorker', () => { rootDir: '/', sys: mockCompilerSystem(), testing: {}, - transformAliasedImportPaths: false, + transformAliasedImportPaths: true, }); }); diff --git a/src/compiler/config/validate-config.ts b/src/compiler/config/validate-config.ts index 53f39e37eb3..e0882f80589 100644 --- a/src/compiler/config/validate-config.ts +++ b/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), }; diff --git a/src/compiler/output-targets/test/output-targets-collection.spec.ts b/src/compiler/output-targets/test/output-targets-collection.spec.ts index 7c78f03254b..f88b1c6c4f0 100644 --- a/src/compiler/output-targets/test/output-targets-collection.spec.ts +++ b/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`', diff --git a/src/declarations/stencil-public-compiler.ts b/src/declarations/stencil-public-compiler.ts index 1d32b8b6f58..dd78f2d0d76 100644 --- a/src/declarations/stencil-public-compiler.ts +++ b/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 diff --git a/src/testing/mocks.ts b/src/testing/mocks.ts index 9767b50729c..f48794de7db 100644 --- a/src/testing/mocks.ts +++ b/src/testing/mocks.ts @@ -46,7 +46,7 @@ export function mockValidatedConfig(overrides: Partial = {}): V srcDir: '/src', sys: createTestingSystem(), testing: {}, - transformAliasedImportPaths: false, + transformAliasedImportPaths: true, rollupConfig: { inputOptions: {}, outputOptions: {}, diff --git a/test/karma/test-sibling/stencil.config.ts b/test/karma/test-sibling/stencil.config.ts index 4f0592fab46..ec788943536 100644 --- a/test/karma/test-sibling/stencil.config.ts +++ b/test/karma/test-sibling/stencil.config.ts @@ -6,6 +6,7 @@ export const config: Config = { outputTargets: [ { type: 'dist', + transformAliasedImportPathsInCollection: false, }, ], globalScript: 'src/global.ts',