[FEATURE] Ability to configure automatic alias creation

s2b · s2b · commit ed6b964b5683 · 2025-08-06T14:38:24.000+02:00
diff --git a/README.md b/README.md
@@ -76,6 +76,10 @@ You can provide additional configuration to the plugin, for example:
     file to provide entrypoints from extensions.
 -   `entrypointIgnorePatterns` (array, default: `["**/node_modules/**", "**/.git/**"]`): Files
     that should be ignored when using wildcards in `ViteEntrypoints.json`.
+-   `aliases` (`true`, `false`, `@` or `EXT`): If set to true, both aliases starting with `EXT:`
+    and `@` are created for all available extension folders. If set to `@`, only `@` aliases
+    are created, if set to `EXT`, only `EXT:` aliases are created. If set to `false`, alias
+    creation is skipped altogether.
 
 ### Fixing CORS issues
 
diff --git a/src/types.ts b/src/types.ts
@@ -3,6 +3,7 @@ export interface UserConfig {
     entrypointFile?: string;
     entrypointIgnorePatterns?: string[];
     debug?: boolean;
+    aliases?: AliasConfig;
 }
 
 export interface PluginConfig<T extends ComposerContext> extends UserConfig {
@@ -11,6 +12,7 @@ export interface PluginConfig<T extends ComposerContext> extends UserConfig {
     composerContext: T;
     entrypointIgnorePatterns: string[];
     debug: boolean;
+    aliases: AliasConfig;
 }
 
 export interface ComposerContext {
@@ -33,3 +35,5 @@ export interface Typo3ProjectContext extends ComposerContext {
 }
 
 export type PluginTarget = "project" | "extension";
+
+export type AliasConfig = true | "EXT" | "@" | false;
diff --git a/src/typo3extension.ts b/src/typo3extension.ts
@@ -65,9 +65,11 @@ export default function typo3extension(
 
             // Add path alias for extension
             config.resolve ??= {};
-            config.resolve.alias = addAliases(config.resolve.alias, [
-                extension,
-            ]);
+            config.resolve.alias = addAliases(
+                config.resolve.alias,
+                [extension],
+                pluginConfig.aliases,
+            );
 
             // Find all vite entrypoints in extension
             entrypoints = findEntrypointsInExtensions(
@@ -101,6 +103,7 @@ export default function typo3extension(
                     entrypoints,
                     pluginConfig.composerContext,
                     logger,
+                    pluginConfig.aliases,
                 );
             }
         },
diff --git a/src/typo3project.ts b/src/typo3project.ts
@@ -99,6 +99,7 @@ export default function typo3project(
             config.resolve.alias = addAliases(
                 config.resolve.alias,
                 availableExtensions,
+                pluginConfig.aliases,
             );
 
             // Find all vite entrypoints in relevant TYPO3 extensions
@@ -144,6 +145,7 @@ export default function typo3project(
                     entrypoints,
                     pluginConfig.composerContext,
                     logger,
+                    pluginConfig.aliases,
                 );
             }
         },
diff --git a/src/utils.ts b/src/utils.ts
@@ -16,6 +16,7 @@ import type {
     UserConfig,
     Typo3ProjectContext,
     Typo3ExtensionContext,
+    AliasConfig,
 } from "./types.js";
 
 export function initializePluginConfig<T extends ComposerContext>(
@@ -42,6 +43,7 @@ export function initializePluginConfig<T extends ComposerContext>(
         entrypointIgnorePatterns: ["**/node_modules/**", "**/.git/**"],
         debug: false,
         composerContext,
+        aliases: true,
         ...userConfig,
     };
 }
@@ -180,15 +182,14 @@ export function outputDebugInformation(
     entrypoints: string[],
     composerContext: ComposerContext,
     logger: Logger,
+    aliasConfig: AliasConfig = true,
 ): void {
     if (availableExtensions.length) {
         const extensionList = availableExtensions.map(
             (extension) => extension.extensionKey,
         );
-        const aliasList = extensionList.reduce(
-            (aliasList: string[], extensionKey) =>
-                aliasList.concat(["@" + extensionKey, "EXT:" + extensionKey]),
-            [],
+        const aliasList = createAliases(availableExtensions, aliasConfig).map(
+            (alias) => alias.find,
         );
         logger.info(
             `The following TYPO3 extensions have been recognized: ${colors.green(extensionList.join(", "))}`,
@@ -231,31 +232,40 @@ export function addRollupInputs(
 export function addAliases(
     alias: AliasOptions | undefined,
     extensions: Typo3ExtensionContext[],
+    config: AliasConfig = true,
 ): AliasOptions {
-    const additionalAliases = extensions.reduce(
-        (aliases: Alias[], extension) => {
-            const replacement = extension.path.endsWith("/")
-                ? extension.path
-                : extension.path + "/";
-            aliases.push({ find: "@" + extension.extensionKey, replacement });
-            aliases.push({
-                find: "EXT:" + extension.extensionKey,
-                replacement,
-            });
-            return aliases;
-        },
-        [],
-    );
-
     alias ??= [];
     if (!Array.isArray(alias)) {
         alias = Object.entries(alias).map((entry) => ({
             find: entry[0],
             replacement: entry[1],
         }));
     }
+    return alias.concat(createAliases(extensions, config));
+}
 
-    return alias.concat(additionalAliases);
+export function createAliases(
+    extensions: Typo3ExtensionContext[],
+    config: AliasConfig,
+) {
+    if (config === false) {
+        return [];
+    }
+    return extensions.reduce((aliases: Alias[], extension) => {
+        const replacement = extension.path.endsWith("/")
+            ? extension.path
+            : extension.path + "/";
+        if (config === "@" || config === true) {
+            aliases.push({ find: "@" + extension.extensionKey, replacement });
+        }
+        if (config === "EXT" || config === true) {
+            aliases.push({
+                find: "EXT:" + extension.extensionKey,
+                replacement,
+            });
+        }
+        return aliases;
+    }, []);
 }
 
 export function readJsonFile(file: string): any {
diff --git a/tests/unit/addAliases.test.ts b/tests/unit/addAliases.test.ts
@@ -114,4 +114,59 @@ describe("addAliases", () => {
             },
         ]);
     });
+    test("set no aliases", () => {
+        expect(
+            addAliases(
+                undefined,
+                [
+                    {
+                        type: "typo3-cms-extension",
+                        extensionKey: "test_extension",
+                        path: "/path/to/dummy/extension1",
+                    },
+                ],
+                false,
+            ),
+        ).toEqual([]);
+    });
+    test("set only @ aliases", () => {
+        expect(
+            addAliases(
+                undefined,
+                [
+                    {
+                        type: "typo3-cms-extension",
+                        extensionKey: "test_extension",
+                        path: "/path/to/dummy/extension1",
+                    },
+                ],
+                "@",
+            ),
+        ).toEqual([
+            {
+                find: "@test_extension",
+                replacement: "/path/to/dummy/extension1/",
+            },
+        ]);
+    });
+    test("set only EXT aliases", () => {
+        expect(
+            addAliases(
+                undefined,
+                [
+                    {
+                        type: "typo3-cms-extension",
+                        extensionKey: "test_extension",
+                        path: "/path/to/dummy/extension1",
+                    },
+                ],
+                "EXT",
+            ),
+        ).toEqual([
+            {
+                find: "EXT:test_extension",
+                replacement: "/path/to/dummy/extension1/",
+            },
+        ]);
+    });
 });
diff --git a/tests/unit/initializePluginConfig.test.ts b/tests/unit/initializePluginConfig.test.ts
@@ -16,6 +16,7 @@ describe("initializePluginConfig", () => {
             entrypointFile: "Configuration/ViteEntrypoints.json",
             entrypointIgnorePatterns: ["**/node_modules/**", "**/.git/**"],
             debug: false,
+            aliases: true,
             composerContext: {
                 type: "project",
                 path: "/path/to/fixtures/composerProject",
@@ -35,6 +36,7 @@ describe("initializePluginConfig", () => {
             entrypointFile: "viteEntrypoints.json",
             entrypointIgnorePatterns: ["**/node_modules/**", "**/.git/**"],
             debug: true,
+            aliases: true,
             composerContext: {
                 type: "project",
                 path: "/path/to/fixtures/composerProject",
@@ -54,6 +56,7 @@ describe("initializePluginConfig", () => {
             entrypointFile: "Configuration/ViteEntrypoints.json",
             entrypointIgnorePatterns: ["**/node_modules/**", "**/.git/**"],
             debug: false,
+            aliases: true,
             composerContext: {
                 type: "typo3-cms-extension",
                 path: "/path/to/fixtures/composerProject/packages/composerExtension/",

Original file line number	Diff line number	Diff line change
`@@ -3,6 +3,7 @@ export interface UserConfig {`
`3`	`3`	`entrypointFile?: string;`
`4`	`4`	`entrypointIgnorePatterns?: string[];`
`5`	`5`	`debug?: boolean;`
	`6`	`+ aliases?: AliasConfig;`
`6`	`7`	`}`
`7`	`8`
`8`	`9`	`export interface PluginConfig<T extends ComposerContext> extends UserConfig {`
`@@ -11,6 +12,7 @@ export interface PluginConfig<T extends ComposerContext> extends UserConfig {`
`11`	`12`	`composerContext: T;`
`12`	`13`	`entrypointIgnorePatterns: string[];`
`13`	`14`	`debug: boolean;`
	`15`	`+ aliases: AliasConfig;`
`14`	`16`	`}`
`15`	`17`
`16`	`18`	`export interface ComposerContext {`
`@@ -33,3 +35,5 @@ export interface Typo3ProjectContext extends ComposerContext {`
`33`	`35`	`}`
`34`	`36`
`35`	`37`	`export type PluginTarget = "project" \| "extension";`
	`38`	`+`
	`39`	`+export type AliasConfig = true \| "EXT" \| "@" \| false;`