feat(lucide-react, lucide-preact, lucide-react-native, lucide-solid, lucide-vue-next): Adjustable icon naming imports (#2328)

* Add override alias import entry files lucide-react

* Make it work

* Setup files for packages

* Revert icon changes

* Remove solid support and add docs

* Adjust docs

* format files

* Fix lucide-vue-next build

* Fix builds

* Fix lucide-svelte

* Add vscode settings option

.gitignore

@@ -16,7 +16,9 @@ outlined
 packages/**/src/icons/*.js
 packages/**/src/icons/*.ts
 packages/**/src/icons/*.tsx
+packages/**/src/aliases/*.ts
 packages/**/src/aliases.ts
+!packages/**/src/aliases/index.ts
 packages/**/src/dynamicIconImports.ts
 packages/**/dynamicIconImports.js
 packages/**/dynamicIconImports.d.ts

docs/.vitepress/sidebar.ts

@@ -46,6 +46,10 @@ const sidebar: UserConfig<DefaultTheme.Config>['themeConfig']['sidebar'] = {
           text: 'Filled icons',
           link: '/guide/advanced/filled-icons',
         },
+        {
+          text: 'Aliased Names',
+          link: '/guide/advanced/aliased-names',
+        },
         // {
         //   text: 'Combining icons',
         // },

docs/guide/advanced/aliased-names.md

@@ -0,0 +1,93 @@
+# Aliased Names
+
+Icons can have multiple names for the same icon. This is because we choose to rename some icons to make them more consistent with the rest of the icon set, or the name was not generic. For example, the `edit-2` icon is renamed to `pen` to make the name more generic, since it is just a pen icon.
+
+Beside aliases names lucide also includes prefixed and suffixed names to use within your project. This is to prevent import name collisions with other libraries or your own code.
+
+```tsx
+// These are all the same icon
+import {
+  Home,
+  HomeIcon,
+  LucideHome,
+} from "lucide-react";
+```
+
+## Choosing import name style
+
+To be consistent in your imports or want to change the autocompletion of Lucide icons in your IDE there an option to able the choose the import name style you want.
+
+This can be done by creating a custom module declaration file to override the lucide imports and turning off the autocomplete in your IDE.
+
+### Turn off autocomplete in your IDE
+
+```json [.vscode/settings.json]
+{
+  "typescript.preferences.autoImportFileExcludePatterns": [
+    "lucide-react", // or
+    "lucide-preact", // or
+    "lucide-react-native", // or
+    "lucide-vue-next",
+  ]
+}
+```
+
+### Create a custom module declaration file
+
+Only available for `lucide-react`, `lucide-preact`, `lucide-react-native`, `lucide-vue-next` package.
+This will enable you to choose the import name style you want to use in your project.
+
+::: code-group
+
+```ts [React]
+declare module "lucide-react" {
+  // Prefixed import names
+  export * from "lucide-react/dist/lucide-react.prefixed";
+  // or
+  // Suffixed import names
+  export * from "lucide-react/dist/lucide-react.suffixed";
+}
+```
+
+```ts [Vue]
+declare module "lucide-vue-next" {
+  // Prefixed import names
+  export * from "lucide-vue-next/dist/lucide-vue-next.prefixed";
+  // or
+  // Suffixed import names
+  export * from "lucide-vue-next/dist/lucide-vue-next.suffixed";
+}
+```
+
+```ts [Preact]
+declare module "lucide-preact" {
+  // Prefixed import names
+  export * from "lucide-preact/dist/lucide-preact.prefixed";
+  // or
+  // Suffixed import names
+  export * from "lucide-preact/dist/lucide-preact.suffixed";
+}
+```
+
+```ts [React Native]
+declare module "lucide-react-native" {
+  // Prefixed import names
+  export * from "lucide-react-native/dist/lucide-react-native.prefixed";
+  // or
+  // Suffixed import names
+  export * from "lucide-react-native/dist/lucide-react-native.suffixed";
+}
+```
+
+:::
+
+Place this in your project root or in a folder where your tsconfig.json is located, or locate it in your defined type directory.
+Easiest way is to create a `@types` folder in your project root and name the file `[package-name].d.ts`.
+
+### Import name styles
+
+| Import Style  | Available imports           | Declaration file import |
+| ------------- | --------------------------- | ----------------------- |
+| Default       | Home, HomeIcon, LucideHome  |                         |
+| Prefixed      | LucideHome                  | [package].prefixed      |
+| Suffixed      | HomeIcon                    | [package].suffixed      |

icons/grid-2x2-plus.json

@@ -29,5 +29,8 @@
     "design",
     "shapes",
     "maths"
+  ],
+  "aliases": [
+    "grid-2-x-2-plus"
   ]
 }

package.json

@@ -29,6 +29,7 @@
     "postinstall": "husky install",
     "lint:es": "eslint .",
     "lint:format": "prettier \"**/*.{js,mjs,ts,jsx,tsx,html,css,scss,json,yml,yaml}\" --check",
+    "lint:format-fix": "prettier \"**/*.{js,mjs,ts,jsx,tsx,html,css,scss,json,yml,yaml}\" --write",
     "lint:json:icons": "ajv --spec=draft2020 -s icon.schema.json -d 'icons/*.json' > /dev/null",
     "lint:json:categories": "ajv --spec=draft2020 -s category.schema.json -d 'categories/*.json' > /dev/null",
     "lint:json": "pnpm run lint:json:icons && pnpm run lint:json:categories",

packages/lucide-angular/package.json

@@ -29,7 +29,7 @@
     "build": "pnpm clean && pnpm copy:license && pnpm build:icons && pnpm build:ng",
     "copy:license": "cp ../../LICENSE ./LICENSE",
     "clean": "rm -rf dist && rm -rf ./src/icons/*.ts",
-    "build:icons": "build-icons --output=./src --templateSrc=./scripts/exportTemplate.mjs --renderUniqueKey --withAliases --aliasesFileExtension=.ts --iconFileExtension=.ts --exportFileName=lucide-icons.ts",
+    "build:icons": "build-icons --output=./src --templateSrc=./scripts/exportTemplate.mjs --renderUniqueKey --withAliases --aliasNamesOnly --aliasesFileExtension=.ts --iconFileExtension=.ts --exportFileName=lucide-icons.ts",
     "build:ng": "ng build --configuration production",
     "test": "ng test --no-watch --no-progress --browsers=ChromeHeadlessCI",
     "test:watch": "ng test",

packages/lucide-angular/src/aliases/index.ts

@@ -0,0 +1 @@
+export * from './aliases';

packages/lucide-preact/rollup.config.mjs

@@ -69,5 +69,25 @@ export default [
     ],
     plugins: [dts()],
   },
+  {
+    input: `src/${outputFileName}.suffixed.ts`,
+    output: [
+      {
+        file: `dist/${outputFileName}.suffixed.d.ts`,
+        format: 'es',
+      },
+    ],
+    plugins: [dts()],
+  },
+  {
+    input: `src/${outputFileName}.prefixed.ts`,
+    output: [
+      {
+        file: `dist/${outputFileName}.prefixed.d.ts`,
+        format: 'es',
+      },
+    ],
+    plugins: [dts()],
+  },
   ...configs,
 ];

packages/lucide-preact/src/aliases/index.ts

@@ -0,0 +1,3 @@
+export * from './aliases';
+export * from './prefixed';
+export * from './suffixed';

packages/lucide-preact/src/lucide-preact.prefixed.ts

@@ -0,0 +1,7 @@
+export * from './icons';
+export * as icons from './icons';
+export * from './aliases/prefixed';
+export * from './types';
+
+export { default as createLucideIcon } from './createLucideIcon';
+export { default as Icon } from './Icon';

packages/lucide-preact/src/lucide-preact.suffixed.ts

@@ -0,0 +1,7 @@
+export * from './icons';
+export * as icons from './icons';
+export * from './aliases/suffixed';
+export * from './types';
+
+export { default as createLucideIcon } from './createLucideIcon';
+export { default as Icon } from './Icon';

packages/lucide-react-native/rollup.config.mjs

@@ -60,5 +60,25 @@ export default [
     ],
     plugins: [dts()],
   },
+  {
+    input: `src/${outputFileName}.suffixed.ts`,
+    output: [
+      {
+        file: `dist/${outputFileName}.suffixed.d.ts`,
+        format: 'es',
+      },
+    ],
+    plugins: [dts()],
+  },
+  {
+    input: `src/${outputFileName}.prefixed.ts`,
+    output: [
+      {
+        file: `dist/${outputFileName}.prefixed.d.ts`,
+        format: 'es',
+      },
+    ],
+    plugins: [dts()],
+  },
   ...configs,
 ];

packages/lucide-react-native/src/aliases/index.ts

@@ -0,0 +1,3 @@
+export * from './aliases';
+export * from './prefixed';
+export * from './suffixed';

packages/lucide-react-native/src/lucide-react-native.prefixed.ts

@@ -0,0 +1,7 @@
+export * from './icons';
+export * as icons from './icons';
+export * from './aliases/prefixed';
+export * from './types';
+
+export { default as createLucideIcon } from './createLucideIcon';
+export { default as Icon } from './Icon';

packages/lucide-react-native/src/lucide-react-native.suffixed.ts

@@ -0,0 +1,7 @@
+export * from './icons';
+export * as icons from './icons';
+export * from './aliases/suffixed';
+export * from './types';
+
+export { default as createLucideIcon } from './createLucideIcon';
+export { default as Icon } from './Icon';

packages/lucide-react/rollup.config.mjs

@@ -111,5 +111,25 @@ export default [
     ],
     plugins: [dts()],
   },
+  {
+    input: `src/${outputFileName}.suffixed.ts`,
+    output: [
+      {
+        file: `dist/${outputFileName}.suffixed.d.ts`,
+        format: 'es',
+      },
+    ],
+    plugins: [dts()],
+  },
+  {
+    input: `src/${outputFileName}.prefixed.ts`,
+    output: [
+      {
+        file: `dist/${outputFileName}.prefixed.d.ts`,
+        format: 'es',
+      },
+    ],
+    plugins: [dts()],
+  },
   ...configs,
 ];

packages/lucide-react/src/aliases/index.ts

@@ -0,0 +1,3 @@
+export * from './aliases';
+export * from './prefixed';
+export * from './suffixed';

packages/lucide-react/src/lucide-react.prefixed.ts

@@ -0,0 +1,6 @@
+export * as icons from './icons';
+export * from './aliases/prefixed';
+export * from './types';
+
+export { default as createLucideIcon } from './createLucideIcon';
+export { default as Icon } from './Icon';

packages/lucide-react/src/lucide-react.suffixed.ts

@@ -0,0 +1,6 @@
+export * as icons from './icons';
+export * from './aliases/suffixed';
+export * from './types';
+
+export { default as createLucideIcon } from './createLucideIcon';
+export { default as Icon } from './Icon';

packages/lucide-solid/src/aliases/index.ts

@@ -0,0 +1,3 @@
+export * from './aliases';
+export * from './prefixed';
+export * from './suffixed';

packages/lucide-static/src/aliases/index.ts

@@ -0,0 +1 @@
+export * from './aliases';

packages/lucide-svelte/src/aliases/index.ts

@@ -0,0 +1,3 @@
+export * from './aliases';
+export * from './prefixed';
+export * from './suffixed';

packages/lucide-svelte/src/lucide-svelte.ts

@@ -1,6 +1,6 @@
-export * from './icons/index.js';
-export * as icons from './icons/index.js';
-export * from './aliases.js';
-export { default as defaultAttributes } from './defaultAttributes.js';
-export * from './types.js';
+export * from './icons/index';
+export * as icons from './icons/index';
+export * from './aliases';
+export { default as defaultAttributes } from './defaultAttributes';
+export * from './types';
 export { default as Icon } from './Icon.svelte';

packages/lucide-vue-next/rollup.config.mjs

@@ -75,5 +75,37 @@ export default [
       }),
     ],
   },
+  {
+    input: `src/${outputFileName}.suffixed.ts`,
+    output: [
+      {
+        file: `dist/${outputFileName}.suffixed.d.ts`,
+        format: 'es',
+      },
+    ],
+    plugins: [
+      dts({
+        compilerOptions: {
+          preserveSymlinks: false,
+        },
+      }),
+    ],
+  },
+  {
+    input: `src/${outputFileName}.prefixed.ts`,
+    output: [
+      {
+        file: `dist/${outputFileName}.prefixed.d.ts`,
+        format: 'es',
+      },
+    ],
+    plugins: [
+      dts({
+        compilerOptions: {
+          preserveSymlinks: false,
+        },
+      }),
+    ],
+  },
   ...configs,
 ];

packages/lucide-vue-next/src/Icon.ts

@@ -1,5 +1,5 @@
 import { type FunctionalComponent, h } from 'vue';
-import { mergeClasses, toKebabCase } from '@lucide/shared';
+import { toKebabCase } from '@lucide/shared';
 import defaultAttributes from './defaultAttributes';
 import { IconNode, LucideProps } from './types';
 

packages/lucide-vue-next/src/aliases/index.ts

@@ -0,0 +1,3 @@
+export * from './aliases';
+export * from './prefixed';
+export * from './suffixed';

packages/lucide-vue-next/src/lucide-vue-next.prefixed.ts

@@ -0,0 +1,6 @@
+export * as icons from './icons';
+export * from './aliases/prefixed';
+export * from './types';
+
+export { default as createLucideIcon } from './createLucideIcon';
+export { default as Icon } from './Icon';

packages/lucide-vue-next/src/lucide-vue-next.suffixed.ts

@@ -0,0 +1,6 @@
+export * as icons from './icons';
+export * from './aliases/suffixed';
+export * from './types';
+
+export { default as createLucideIcon } from './createLucideIcon';
+export { default as Icon } from './Icon';

packages/lucide-vue/src/aliases/index.ts

@@ -0,0 +1 @@
+export * from './aliases';

packages/lucide/src/aliases/index.ts

@@ -0,0 +1 @@
+export * from './aliases';

tools/build-icons/.swcrc

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://swc.rs/schema.json",
+
+  "jsc": {
+    "parser": {
+      "syntax": "ecmascript",
+      "jsx": true,
+      "dynamicImport": true
+    },
+    "target": "esnext",
+    "loose": false,
+    "externalHelpers": false,
+    "keepClassNames": true
+  },
+  "module": {
+    "type": "es6",
+    "strict": true,
+    "strictMode": true,
+    "lazy": false,
+    "noInterop": false
+  },
+  "minify": false,
+  "sourceMaps": true,
+  "env": {
+    "targets": {
+      "node": "current"
+    },
+    "mode": "entry",
+    "coreJs": "3"
+  }
+
+}

tools/build-icons/building/aliases/generateAliasesFiles.mjs

@@ -2,23 +2,10 @@ import path from 'path';
 import fs from 'fs';
 // eslint-disable-next-line import/no-extraneous-dependencies
 import { toPascalCase, resetFile, appendFile } from '@lucide/helpers';
-import { deprecationReasonTemplate } from '../utils/deprecationReasonTemplate.mjs';
+import deprecationReasonTemplate from '../../utils/deprecationReasonTemplate.mjs';
+import getExportString from './getExportString.mjs';
 
-const getImportString = (
-  componentName,
-  iconName,
-  aliasImportFileExtension,
-  deprecated,
-  deprecationReason = '',
-) =>
-  deprecated
-    ? `export {\n` +
-      `  /** @deprecated ${deprecationReason} */\n` +
-      `  default as ${componentName}\n` +
-      `} from './icons/${iconName}${aliasImportFileExtension}';\n`
-    : `export { default as ${componentName} } from './icons/${iconName}${aliasImportFileExtension}';\n`;
-
-export default async function generateAliasesFile({
+export default async function generateAliasesFiles({
   iconNodes,
   outputDirectory,
   fileExtension,
@@ -30,11 +17,25 @@ export default async function generateAliasesFile({
   showLog = true,
 }) {
   const iconsDistDirectory = path.join(outputDirectory, `icons`);
-  const fileName = path.basename(`aliases${fileExtension}`);
   const icons = Object.keys(iconNodes);
 
-  // Reset file
-  resetFile(fileName, outputDirectory);
+  const destinationDirectory = path.join(outputDirectory, 'aliases');
+
+  const aliasFileName = path.basename(`aliases${fileExtension}`);
+  const aliasPrefixesFileName = path.basename(`prefixed${fileExtension}`);
+  const aliasSuffixFileName = path.basename(`suffixed${fileExtension}`);
+
+  if (!fs.existsSync(destinationDirectory)) {
+    fs.mkdirSync(destinationDirectory);
+  }
+
+  // Reset files
+  resetFile(aliasFileName, destinationDirectory);
+
+  if (!aliasNamesOnly) {
+    resetFile(aliasPrefixesFileName, destinationDirectory);
+    resetFile(aliasSuffixFileName, destinationDirectory);
+  }
 
   // Generate Import for Icon VNodes
   await Promise.all(
@@ -50,19 +51,32 @@ export default async function generateAliasesFile({
         return alias;
       });
 
-      let importString = '';
+      let aliasFileContent = '';
+      let aliasPrefixesFileContent = '';
+      let aliasSuffixFileContent = '';
 
       if ((iconAliases != null && Array.isArray(iconAliases)) || !aliasNamesOnly) {
-        if (index > 0) {
-          importString += '\n';
+        if (index > 0 && aliasPrefixesFileContent !== '') {
+          aliasPrefixesFileContent += '\n';
         }
 
-        importString += `// ${componentName} aliases\n`;
+        if (index > 0 && aliasSuffixFileContent !== '') {
+          aliasSuffixFileContent += '\n';
         }
 
         if (!aliasNamesOnly) {
-        importString += getImportString(`${componentName}Icon`, iconName, aliasImportFileExtension);
-        importString += getImportString(
+          aliasPrefixesFileContent += `// ${componentName} aliases\n`;
+          aliasSuffixFileContent += `// ${componentName} aliases\n`;
+        }
+      }
+
+      if (!aliasNamesOnly) {
+        aliasSuffixFileContent += getExportString(
+          `${componentName}Icon`,
+          iconName,
+          aliasImportFileExtension,
+        );
+        aliasPrefixesFileContent += getExportString(
           `Lucide${componentName}`,
           iconName,
           aliasImportFileExtension,
@@ -95,7 +109,12 @@ export default async function generateAliasesFile({
 
             const exportFileIcon = separateAliasesFile ? alias.name : iconName;
 
-            importString += getImportString(
+            if (index > 0) {
+              aliasFileContent += '\n';
+            }
+
+            aliasFileContent += `// ${componentName} aliases\n`;
+            aliasFileContent += getExportString(
               componentNameAlias,
               exportFileIcon,
               aliasImportFileExtension,
@@ -104,7 +123,7 @@ export default async function generateAliasesFile({
             );
 
             if (!aliasNamesOnly) {
-              importString += getImportString(
+              aliasSuffixFileContent += getExportString(
                 `${componentNameAlias}Icon`,
                 exportFileIcon,
                 aliasImportFileExtension,
@@ -112,7 +131,7 @@ export default async function generateAliasesFile({
                 deprecationReason,
               );
 
-              importString += getImportString(
+              aliasPrefixesFileContent += getExportString(
                 `Lucide${componentNameAlias}`,
                 exportFileIcon,
                 aliasImportFileExtension,
@@ -124,13 +143,25 @@ export default async function generateAliasesFile({
         );
       }
 
-      appendFile(importString, fileName, outputDirectory);
+      appendFile(aliasFileContent, aliasFileName, destinationDirectory);
+
+      if (!aliasNamesOnly) {
+        appendFile(aliasPrefixesFileContent, aliasPrefixesFileName, destinationDirectory);
+        appendFile(aliasSuffixFileContent, aliasSuffixFileName, destinationDirectory);
+      }
     }),
   );
 
-  appendFile('\n', fileName, outputDirectory);
+  appendFile('\n', aliasFileName, destinationDirectory);
+
+  if (!aliasNamesOnly) {
+    appendFile('\n', aliasPrefixesFileName, destinationDirectory);
+    appendFile('\n', aliasSuffixFileName, destinationDirectory);
+  }
 
   if (showLog) {
-    console.log(`Successfully generated ${fileName} file`);
+    console.log(`Successfully generated src/aliases/${aliasFileName} file`);
+    console.log(`Successfully generated src/aliases/${aliasPrefixesFileName} file`);
+    console.log(`Successfully generated src/aliases/${aliasSuffixFileName} file`);
   }
 }

tools/build-icons/building/aliases/getExportString.mjs

@@ -0,0 +1,15 @@
+const getExportString = (
+  componentName,
+  iconName,
+  aliasImportFileExtension,
+  deprecated,
+  deprecationReason = '',
+) =>
+  deprecated
+    ? `export {\n` +
+      `  /** @deprecated ${deprecationReason} */\n` +
+      `  default as ${componentName}\n` +
+      `} from '../icons/${iconName}${aliasImportFileExtension}';\n`
+    : `export { default as ${componentName} } from '../icons/${iconName}${aliasImportFileExtension}';\n`;
+
+export default getExportString;

tools/build-icons/building/generateIconFiles.mjs

@@ -2,7 +2,7 @@ import fs from 'fs';
 import path from 'path';
 import prettier from 'prettier';
 import { readSvg, toPascalCase } from '@lucide/helpers';
-import { deprecationReasonTemplate } from '../utils/deprecationReasonTemplate.mjs';
+import deprecationReasonTemplate from '../utils/deprecationReasonTemplate.mjs';
 
 export default ({
   iconNodes,

tools/build-icons/cli.mjs

@@ -8,7 +8,7 @@ import renderIconsObject from './render/renderIconsObject.mjs';
 import generateIconFiles from './building/generateIconFiles.mjs';
 import generateExportsFile from './building/generateExportsFile.mjs';
 
-import generateAliasesFile from './building/generateAliasesFile.mjs';
+import generateAliasesFiles from './building/aliases/generateAliasesFiles.mjs';
 // eslint-disable-next-line import/no-named-as-default, import/no-named-as-default-member
 import getIconMetaData from './utils/getIconMetaData.mjs';
 import generateDynamicImports from './building/generateDynamicImports.mjs';
@@ -65,7 +65,7 @@ async function buildIcons() {
   });
 
   if (withAliases) {
-    await generateAliasesFile({
+    await generateAliasesFiles({
       iconNodes: icons,
       iconMetaData,
       aliasNamesOnly,
@@ -99,7 +99,7 @@ async function buildIcons() {
 }
 
 try {
-  buildIcons();
+  await buildIcons();
 } catch (error) {
   console.error(error);
 }

tools/build-icons/package.json

@@ -11,7 +11,7 @@
     "build-icons": "./cli.mjs"
   },
   "engines": {
-    "node": ">= 16"
+    "node": ">= 20"
   },
   "keywords": [],
   "author": "",

tools/build-icons/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "strict": false,
+    "declaration": true,
+    "noEmitOnError": true,
+    "noFallthroughCasesInSwitch": true,
+    "moduleResolution": "node",
+    "module": "ESNext",
+    "target": "ESNext",
+    "esModuleInterop": true,
+    "allowJs": true,
+    "lib": ["esnext"],
+    "resolveJsonModule": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+  },
+}

tools/build-icons/utils/deprecationReasonTemplate.mjs

@@ -1,9 +1,11 @@
-export function deprecationReasonTemplate(
+export default function deprecationReasonTemplate(
   deprecationReason,
   { componentName, iconName, toBeRemovedInVersion },
 ) {
   const removalNotice = toBeRemovedInVersion
-    ? ` This ${deprecationReason.startsWith('icon') ? 'icon' : 'alias'} will be removed in ${toBeRemovedInVersion}`
+    ? ` This ${
+        deprecationReason.startsWith('icon') ? 'icon' : 'alias'
+      } will be removed in ${toBeRemovedInVersion}`
     : '';
 
   switch (deprecationReason) {
@@ -13,5 +15,7 @@ export function deprecationReasonTemplate(
       return `The name of this icon was changed because it didn't meet our guidelines anymore, use {@link ${componentName}} instead.${removalNotice}`;
     case 'icon.brand':
       return `Brand icons have been deprecated and are due to be removed, please refer to https://github.com/lucide-icons/lucide/issues/670. We recommend using https://simpleicons.org/?q=${iconName} instead.${removalNotice}`;
+    default:
+      return '';
   }
 }