feat(config): allow suppressing reserved public name warning (#6389)

deleonio · web-flow · commit 341fec4ed016 · 2025-09-23T06:16:51.000Z
* feat(config): allow suppressing reserved public name warning

* chore(prettier): format prop decorator map call

* test(config): cover suppressReservedPublicNameWarnings
diff --git a/src/compiler/config/test/validate-config.spec.ts b/src/compiler/config/test/validate-config.spec.ts
@@ -116,6 +116,19 @@ describe('validation', () => {
     });
   });
 
+  describe('suppressReservedPublicNameWarnings', () => {
+    it.each([true, false])('sets suppressReservedPublicNameWarnings to %p when provided', (bool) => {
+      userConfig.suppressReservedPublicNameWarnings = bool;
+      const { config } = validateConfig(userConfig, bootstrapConfig);
+      expect(config.suppressReservedPublicNameWarnings).toBe(bool);
+    });
+
+    it('defaults suppressReservedPublicNameWarnings to false', () => {
+      const { config } = validateConfig(userConfig, bootstrapConfig);
+      expect(config.suppressReservedPublicNameWarnings).toBe(false);
+    });
+  });
+
   describe('enableCache', () => {
     it('set enableCache true', () => {
       userConfig.enableCache = true;
diff --git a/src/compiler/config/validate-config.ts b/src/compiler/config/validate-config.ts
@@ -205,6 +205,7 @@ export const validateConfig = (
   setBooleanConfig(validatedConfig, 'autoprefixCss', null, validatedConfig.buildEs5);
   setBooleanConfig(validatedConfig, 'validateTypes', null, !validatedConfig._isTesting);
   setBooleanConfig(validatedConfig, 'allowInlineScripts', null, true);
+  setBooleanConfig(validatedConfig, 'suppressReservedPublicNameWarnings', null, false);
 
   if (!isString(validatedConfig.taskQueue)) {
     validatedConfig.taskQueue = 'async';
diff --git a/src/compiler/transformers/decorators-to-static/convert-decorators.ts b/src/compiler/transformers/decorators-to-static/convert-decorators.ts
@@ -119,6 +119,7 @@ const visitClassDeclaration = (
   // parse member decorators (Prop, State, Listen, Event, Method, Element and Watch)
   if (decoratedMembers.length > 0) {
     propDecoratorsToStatic(
+      config,
       diagnostics,
       decoratedMembers,
       typeChecker,
diff --git a/src/compiler/transformers/decorators-to-static/method-decorator.ts b/src/compiler/transformers/decorators-to-static/method-decorator.ts
@@ -89,7 +89,7 @@ const parseMethodDecorator = (
   }
 
   // Validate if the method name does not conflict with existing public names
-  validatePublicName(diagnostics, methodName, '@Method()', 'method', method.name);
+  validatePublicName(config, diagnostics, methodName, '@Method()', 'method', method.name);
 
   const methodMeta: d.ComponentCompilerStaticMethod = {
     complexType: {
diff --git a/src/compiler/transformers/decorators-to-static/prop-decorator.ts b/src/compiler/transformers/decorators-to-static/prop-decorator.ts
@@ -30,6 +30,7 @@ import { getDecoratorParameters, isDecoratorNamed } from './decorator-utils';
  * @param decoratorName the name of the decorator to look for
  */
 export const propDecoratorsToStatic = (
+  config: d.ValidatedConfig,
   diagnostics: d.Diagnostic[],
   decoratedProps: ts.ClassElement[],
   typeChecker: ts.TypeChecker,
@@ -39,7 +40,7 @@ export const propDecoratorsToStatic = (
 ): void => {
   const properties = decoratedProps
     .filter((prop) => ts.isPropertyDeclaration(prop) || ts.isGetAccessor(prop))
-    .map((prop) => parsePropDecorator(diagnostics, typeChecker, program, prop, decoratorName, newMembers))
+    .map((prop) => parsePropDecorator(config, diagnostics, typeChecker, program, prop, decoratorName, newMembers))
     .filter((prop): prop is ts.PropertyAssignment => prop != null);
 
   if (properties.length > 0) {
@@ -59,6 +60,7 @@ export const propDecoratorsToStatic = (
  * @returns a property assignment expression to be added to the Stencil component's class
  */
 const parsePropDecorator = (
+  config: d.ValidatedConfig,
   diagnostics: d.Diagnostic[],
   typeChecker: ts.TypeChecker,
   program: ts.Program,
@@ -88,7 +90,7 @@ const parsePropDecorator = (
     warn.messageText = `The @Prop() name "${propName}" looks like an event. Please use the "@Event()" decorator to expose events instead, not properties or methods.`;
     augmentDiagnosticWithNode(warn, prop.name);
   } else {
-    validatePublicName(diagnostics, propName, '@Prop()', 'prop', prop.name);
+    validatePublicName(config, diagnostics, propName, '@Prop()', 'prop', prop.name);
   }
 
   const symbol = typeChecker.getSymbolAtLocation(prop.name);
diff --git a/src/compiler/transformers/reserved-public-members.ts b/src/compiler/transformers/reserved-public-members.ts
@@ -14,12 +14,17 @@ import type * as d from '../../declarations';
  * @param node the TypeScript AST node at which the class member is defined
  */
 export const validatePublicName = (
+  config: d.ValidatedConfig,
   diagnostics: d.Diagnostic[],
   memberName: string,
   decorator: string,
   memberType: string,
   node: ts.Node,
 ): void => {
+  if (config.suppressReservedPublicNameWarnings) {
+    return;
+  }
+
   if (RESERVED_PUBLIC_MEMBERS.has(memberName.toLowerCase())) {
     const warn = buildWarn(diagnostics);
     warn.messageText = [
diff --git a/src/declarations/stencil-public-compiler.ts b/src/declarations/stencil-public-compiler.ts
@@ -152,6 +152,11 @@ export interface StencilConfig {
    * This behavior defaults to `true`, but may be opted-out of by setting this flag to `false`.
    */
   transformAliasedImportPaths?: boolean;
+  /**
+   * When `true`, Stencil will suppress diagnostics which warn about public members using reserved names
+   * (for example, decorating a method named `focus` with `@Method()`). Defaults to `false`.
+   */
+  suppressReservedPublicNameWarnings?: boolean;
   /**
    * When `true`, we will validate a project's `package.json` based on the output target the user has designated
    * as `isPrimaryPackageOutputTarget: true` in their Stencil config.
diff --git a/src/testing/mocks.ts b/src/testing/mocks.ts
@@ -45,6 +45,7 @@ export function mockValidatedConfig(overrides: Partial<d.ValidatedConfig> = {}):
     rootDir,
     srcDir: '/src',
     srcIndexHtml: 'src/index.html',
+    suppressReservedPublicNameWarnings: false,
     sys: createTestingSystem(),
     testing: {},
     transformAliasedImportPaths: true,
@@ -102,6 +103,7 @@ export function mockConfig(overrides: Partial<d.UnvalidatedConfig> = {}): d.Unva
     },
     rootDir,
     sourceMap: true,
+    suppressReservedPublicNameWarnings: false,
     sys,
     testing: null,
     validateTypes: false,

Original file line number	Diff line number	Diff line change
`@@ -89,7 +89,7 @@ const parseMethodDecorator = (`
`89`	`89`	`}`
`90`	`90`
`91`	`91`	`// Validate if the method name does not conflict with existing public names`
`92`		`- validatePublicName(diagnostics, methodName, '@Method()', 'method', method.name);`
	`92`	`+ validatePublicName(config, diagnostics, methodName, '@Method()', 'method', method.name);`
`93`	`93`
`94`	`94`	`const methodMeta: d.ComponentCompilerStaticMethod = {`
`95`	`95`	`complexType: {`