@wkovacs64/add-icon 0.1.0-dev.3b555c68

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Justin R. Hall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+# @wkovacs64/add-icon
+
+A command-line tool to download icons from the [Iconify Framework](https://iconify.design/) and
+apply custom transformations.
+
+## Installation
+
+Add it to your project:
+
+```bash
+npm install @wkovacs64/add-icon
+```
+
+Or use it directly with npx without installing:
+
+```bash
+npx @wkovacs64/add-icon heroicons:arrow-up-circle
+```
+
+## Usage
+
+### Basic Usage
+
+Download an icon:
+
+```bash
+npx @wkovacs64/add-icon heroicons:arrow-up-circle
+```
+
+Specify an output directory:
+
+```bash
+npx @wkovacs64/add-icon heroicons:arrow-up-circle --output-dir ./my-icons
+```
+
+### Transformations
+
+The tool fetches SVG icons directly from the Iconify API with width and height attributes removed automatically. You can add custom transformations for more advanced modifications.
+
+### Custom Transformations
+
+You can write custom transforms in either JavaScript or TypeScript!
+
+#### JavaScript Transform
+
+Create a custom transform file (e.g., `my-transform.js`):
+
+```js
+/**
+ * Custom transform to add a title element to SVG
+ * @param {Object} args - Transform arguments
+ * @param {string} args.svg - SVG content
+ * @param {string} args.iconName - Icon name (e.g., 'heroicons:arrow-up-circle')
+ * @param {string} args.prefix - Icon set prefix (e.g., 'heroicons')
+ * @param {string} args.name - Icon name without prefix (e.g., 'arrow-up-circle')
+ * @returns {string} - Transformed SVG
+ */
+export default function addTitle(args) {
+  const titleElement = `<title>${args.iconName}</title>`;
+  return args.svg.replace(/<svg([^>]*)>/, `<svg$1>${titleElement}`);
+}
+```
+
+#### TypeScript Transform
+
+Create a custom transform file (e.g., `my-transform.ts`) that will be imported directly:
+
+```ts
+import type { TransformArgs } from '@wkovacs64/add-icon';
+
+/**
+ * Custom transform to add a title element to SVG
+ * @param args - Transform arguments containing SVG content and icon information
+ * @returns The transformed SVG
+ */
+export default function addTitle(args: TransformArgs): string {
+  const titleElement = `<title>${args.iconSet}:${args.iconName}</title>`;
+  return args.svg.replace(/<svg([^>]*)>/, `<svg$1>${titleElement}`);
+}
+```
+
+Then use it with the CLI:
+
+```bash
+# JavaScript transform
+npx @wkovacs64/add-icon heroicons:arrow-up-circle --transform ./my-transform.js
+
+# TypeScript transform
+npx @wkovacs64/add-icon heroicons:arrow-up-circle --transform ./my-transform.ts
+```
+
+## Configuration File
+
+You can create a configuration file in your project root, using either JavaScript (`add-icon.config.js`) or TypeScript (`add-icon.config.ts`).
+
+### JavaScript Configuration
+
+```js
+// Define custom transform
+function addCustomAttribute(args) {
+  return args.svg.replace(/<svg/, `<svg data-icon="${args.iconName}"`);
+}
+
+export default {
+  outputDir: './assets/icons',
+  transforms: [addCustomAttribute],
+};
+```
+
+### TypeScript Configuration
+
+You can create a TypeScript configuration file and the tool will import it directly:
+
+```ts
+import type { IconifyConfig, TransformArgs } from '@wkovacs64/add-icon';
+
+// Define custom transform
+function addCustomAttribute(args: TransformArgs): string {
+  return args.svg.replace(/<svg/, `<svg data-icon="${args.iconName}"`);
+}
+
+const config = {
+  outputDir: './assets/icons',
+  transforms: [addCustomAttribute],
+} satisfies IconifyConfig;
+
+export default config;
+```
+
+> **Note:** TypeScript configuration and transform files are compiled in-memory using esbuild, without creating temporary JavaScript files. This provides a seamless TypeScript experience with no extra build steps.
+
+## Using as a Library
+
+You can also use iconify-cli as a library in your own projects:
+
+### JavaScript
+
+```js
+import { downloadIcon } from '@wkovacs64/add-icon';
+
+// Create custom transform
+function addCustomAttribute(args) {
+  return args.svg.replace(/<svg/, `<svg data-custom="${args.iconSet}"`);
+}
+
+// Download an icon with transforms
+async function downloadCustomIcon() {
+  const iconPath = await downloadIcon('heroicons:heart', {
+    outputDir: './icons',
+    transforms: [addCustomAttribute],
+  });
+
+  console.log(`Icon saved to: ${iconPath}`);
+}
+
+downloadCustomIcon();
+```
+
+### TypeScript
+
+```ts
+import { downloadIcon, type TransformArgs } from '@wkovacs64/add-icon';
+
+// Create custom transform
+const addCustomAttribute = (args: TransformArgs): string => {
+  return args.svg.replace(/<svg/, `<svg data-custom="${args.iconSet}"`);
+};
+
+// Download an icon with transforms
+async function downloadCustomIcon(): Promise<void> {
+  try {
+    const iconPath = await downloadIcon('heroicons:heart', {
+      outputDir: './icons',
+      transforms: [addCustomAttribute],
+    });
+
+    console.log(`Icon saved to: ${iconPath}`);
+  } catch (error) {
+    console.error(
+      'Error downloading icon:',
+      error instanceof Error ? error.message : String(error),
+    );
+  }
+}
+
+downloadCustomIcon();
+```
+
+## License
+
+MIT

package/bin/add-icon.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+// Import and run the CLI module
+import '../dist/index.js';

package/dist/config.d.ts

@@ -0,0 +1,11 @@
+import type { IconifyConfig } from './types.js';
+/**
+ * Default configuration
+ */
+export declare const defaultConfig: IconifyConfig;
+/**
+ * Loads configuration from file if it exists
+ * @param configPath - Path to config file
+ * @returns Configuration object
+ */
+export declare function loadConfig(configPath?: string): Promise<IconifyConfig>;

package/dist/config.js

@@ -0,0 +1,55 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { importModule } from './import-module.js';
+/**
+ * Default configuration
+ */
+export const defaultConfig = {
+    outputDir: '.', // Current directory
+};
+/**
+ * Loads configuration from file if it exists
+ * @param configPath - Path to config file
+ * @returns Configuration object
+ */
+export async function loadConfig(configPath) {
+    try {
+        // If a specific config path is provided, use it
+        if (configPath) {
+            // Use the unified import method for both JS and TS files
+            const config = await importModule(configPath);
+            return { ...defaultConfig, ...config.default };
+        }
+        // Try to find a config file in the current directory, checking both JS and TS
+        const jsConfigPath = path.resolve(process.cwd(), 'add-icon.config.js');
+        const tsConfigPath = path.resolve(process.cwd(), 'add-icon.config.ts');
+        // Check for TypeScript config first
+        if (existsSync(tsConfigPath)) {
+            try {
+                const config = await importModule(tsConfigPath);
+                return { ...defaultConfig, ...config.default };
+            }
+            catch (err) {
+                console.error('Error loading TypeScript config, falling back to default config:', err);
+                return defaultConfig;
+            }
+        }
+        // Then check for JavaScript config
+        if (existsSync(jsConfigPath)) {
+            try {
+                const config = await importModule(jsConfigPath);
+                return { ...defaultConfig, ...config.default };
+            }
+            catch (err) {
+                console.error('Error loading JavaScript config, falling back to default config:', err);
+                return defaultConfig;
+            }
+        }
+        // Fall back to default config
+        return defaultConfig;
+    }
+    catch (error) {
+        console.error('Error loading config, using default config:', error);
+        return defaultConfig;
+    }
+}

package/dist/iconify.d.ts

@@ -0,0 +1,17 @@
+import type { IconifyConfig } from './types.js';
+/**
+ * Parses an icon reference into iconSet and iconName
+ * @param iconReference - Reference in format 'iconSet:iconName'
+ * @returns Object with iconSet and iconName
+ */
+export declare function parseIconReference(iconReference: string): {
+    iconSet: string;
+    iconName: string;
+};
+/**
+ * Downloads an icon and applies transforms
+ * @param iconReference - Icon reference (e.g., 'heroicons:arrow-up-circle')
+ * @param config - Configuration options
+ * @returns Path to saved icon file
+ */
+export declare function downloadIcon(iconReference: string, config: IconifyConfig): Promise<string>;

package/dist/iconify.js

@@ -0,0 +1,78 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Parses an icon reference into iconSet and iconName
+ * @param iconReference - Reference in format 'iconSet:iconName'
+ * @returns Object with iconSet and iconName
+ */
+export function parseIconReference(iconReference) {
+    const parts = iconReference.split(':');
+    if (parts.length !== 2 || !parts[0] || !parts[1]) {
+        throw new Error(`Invalid icon reference: ${iconReference}. Expected format: iconSet:iconName`);
+    }
+    return {
+        iconSet: parts[0],
+        iconName: parts[1],
+    };
+}
+/**
+ * Fetches icon SVG directly from Iconify API
+ * @param iconSet - Icon set name
+ * @param iconName - Icon name
+ * @returns Promise with SVG string
+ */
+async function fetchIconSvg(iconSet, iconName) {
+    // Using width=unset parameter to remove width/height attributes automatically
+    const apiUrl = `https://api.iconify.design/${iconSet}/${iconName}.svg?width=unset`;
+    try {
+        const response = await fetch(apiUrl);
+        if (!response.ok) {
+            throw new Error(`HTTP error! Status: ${response.status}`);
+        }
+        return await response.text();
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to fetch icon SVG: ${errorMessage}`);
+    }
+}
+/**
+ * Downloads an icon and applies transforms
+ * @param iconReference - Icon reference (e.g., 'heroicons:arrow-up-circle')
+ * @param config - Configuration options
+ * @returns Path to saved icon file
+ */
+export async function downloadIcon(iconReference, config) {
+    try {
+        const { iconSet, iconName } = parseIconReference(iconReference);
+        // Ensure the output directory exists
+        if (!fs.existsSync(config.outputDir)) {
+            fs.mkdirSync(config.outputDir, { recursive: true });
+        }
+        // Fetch SVG directly with width=unset parameter to remove width/height attributes
+        let svg = await fetchIconSvg(iconSet, iconName);
+        // Apply custom transforms if specified
+        if (config.transforms && config.transforms.length > 0) {
+            for (const transform of config.transforms) {
+                // Create transform arguments object
+                const transformArgs = {
+                    svg,
+                    iconSet,
+                    iconName,
+                };
+                // Apply transform
+                svg = await Promise.resolve(transform(transformArgs));
+            }
+        }
+        // Create file name
+        const fileName = `${iconSet}-${iconName}.svg`;
+        const filePath = path.join(config.outputDir, fileName);
+        // Write the SVG file
+        fs.writeFileSync(filePath, svg, 'utf8');
+        return filePath;
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to download icon: ${errorMessage}`);
+    }
+}

package/dist/import-module.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Imports a module file (JavaScript or TypeScript) by processing it with esbuild
+ * @param filePath - Path to module file (JS or TS)
+ * @returns Module exports
+ */
+export declare function importModule(filePath: string): Promise<any>;

package/dist/import-module.js

@@ -0,0 +1,35 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import * as esbuild from 'esbuild';
+/**
+ * Imports a module file (JavaScript or TypeScript) by processing it with esbuild
+ * @param filePath - Path to module file (JS or TS)
+ * @returns Module exports
+ */
+export async function importModule(filePath) {
+    const absolutePath = path.resolve(filePath);
+    try {
+        // Read the module file content
+        const code = await fs.readFile(absolutePath, "utf-8");
+        // Determine the appropriate loader based on file extension
+        const loader = absolutePath.endsWith('.ts') ? 'ts' : 'js';
+        // Use esbuild to transform the code to ESM JS
+        const result = await esbuild.transform(code, {
+            loader, // Automatically use the appropriate loader
+            format: "esm", // Output format
+            sourcemap: false, // Disable source maps for data URI
+            sourcefile: absolutePath, // Helps with error messages
+            target: 'esnext',
+        });
+        const jsCode = result.code;
+        // Create data URI and import
+        const base64Code = Buffer.from(jsCode).toString("base64");
+        const dataUri = `data:text/javascript;base64,${base64Code}`;
+        // Import the transformed code as a module
+        return await import(dataUri);
+    }
+    catch (error) {
+        console.error(`Error importing module ${filePath} with esbuild:`, error);
+        throw error;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import type { IconTransform, TransformArgs } from './types.js';
+export type { IconTransform, TransformArgs };
+export { downloadIcon, parseIconReference } from './iconify.js';

package/dist/index.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import url from 'node:url';
+import os from 'node:os';
+import { Command } from 'commander';
+import { downloadIcon } from './iconify.js';
+import { loadConfig } from './config.js';
+import { importModule } from './import-module.js';
+import { getPackageInfo } from './package-info.js';
+// Re-export other useful functions
+export { downloadIcon, parseIconReference } from './iconify.js';
+// Create CLI program
+const program = new Command();
+// Set up the program with package info
+const setupProgram = async () => {
+    const { name, version, description } = await getPackageInfo();
+    return program
+        .name(name.split('/').pop() || name)
+        .description(description)
+        .version(version, '-v, --version', 'Output the current version')
+        .argument('<icon>', 'Icon reference (e.g., heroicons:arrow-up-circle)')
+        .option('-o, --output-dir <dir>', 'Directory to save icon')
+        .option('-c, --config <path>', 'Path to config file')
+        .option('-t, --transform <path>', 'Path to custom transform module (.js or .ts)');
+};
+// Initialize the program
+const initializedProgram = await setupProgram();
+initializedProgram.action(async (icon, options) => {
+    try {
+        // Load config (first from config file, then override with CLI options)
+        const config = await loadConfig(options.config);
+        // Override output directory if specified in CLI
+        if (options.outputDir) {
+            config.outputDir = options.outputDir;
+        }
+        // Load custom transform if specified
+        if (options.transform) {
+            try {
+                const transformPath = path.resolve(process.cwd(), options.transform);
+                let customTransform;
+                try {
+                    // Use unified import method for both JS and TS files
+                    customTransform = await importModule(transformPath);
+                }
+                catch (err) {
+                    const errorMessage = err instanceof Error ? err.message : String(err);
+                    console.error(`Error loading transform: ${errorMessage}`);
+                    process.exit(1);
+                }
+                if (customTransform && typeof customTransform.default === 'function') {
+                    config.transforms = [customTransform.default];
+                }
+                else {
+                    console.error('Custom transform must export a default function');
+                    process.exit(1);
+                }
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                console.error(`Failed to load custom transform: ${errorMessage}`);
+                process.exit(1);
+            }
+        }
+        // Download the icon
+        console.log(`Downloading icon: ${icon}...`);
+        const savedPath = await downloadIcon(icon, config);
+        console.log(`✓ Icon saved to: ${savedPath}`);
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        console.error(`Error: ${errorMessage}`);
+        process.exit(1);
+    }
+});
+const __filename = url.fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// This logic only runs when executed directly as CLI, not when imported as a library
+if (os.platform() === 'win32'
+    ? process.argv[1] === __filename
+    : process.argv[1] === __filename || process.argv[1] === __dirname) {
+    // Parse command line arguments
+    program.parse(process.argv);
+}

package/dist/package-info.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Loads package info from package.json
+ * @returns Package info with name, version, and description
+ */
+export declare function getPackageInfo(): Promise<{
+    name: string;
+    version: string;
+    description: string;
+}>;

package/dist/package-info.js

@@ -0,0 +1,34 @@
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+/**
+ * Loads package info from package.json
+ * @returns Package info with name, version, and description
+ */
+export async function getPackageInfo() {
+    // Get the directory of the current module
+    const currentFileUrl = import.meta.url;
+    const currentFilePath = fileURLToPath(currentFileUrl);
+    const currentDir = path.dirname(currentFilePath);
+    // Go up one level from src/ to the package root
+    const packageJsonPath = path.resolve(currentDir, '..', 'package.json');
+    try {
+        // Read and parse package.json
+        const packageJsonContent = await fs.readFile(packageJsonPath, 'utf-8');
+        const packageJson = JSON.parse(packageJsonContent);
+        return {
+            name: packageJson.name || 'unknown',
+            version: packageJson.version || '0.0.0',
+            description: packageJson.description || 'unknown',
+        };
+    }
+    catch (error) {
+        console.warn('Failed to read package.json:', error);
+        // Fallback values
+        return {
+            name: 'unknown',
+            version: '0.0.0',
+            description: 'unknown',
+        };
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Arguments passed to transform functions
+ */
+export type TransformArgs = {
+    /** The SVG content as a string */
+    svg: string;
+    /** The icon set (e.g., 'heroicons') */
+    iconSet: string;
+    /** The icon name (e.g., 'arrow-up-circle') */
+    iconName: string;
+};
+/**
+ * SVG transformation function type
+ */
+export type IconTransform = (args: TransformArgs) => Promise<string> | string;
+/**
+ * Configuration options for the Iconify CLI
+ */
+export type IconifyConfig = {
+    /** Directory to output icons */
+    outputDir: string;
+    /** Array of transform functions to apply to icons */
+    transforms?: IconTransform[];
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@wkovacs64/add-icon",
+  "version": "0.1.0-dev.3b555c68",
+  "description": "CLI tool to download and transform icons from Iconify",
+  "keywords": [
+    "iconify",
+    "icons",
+    "svg",
+    "cli",
+    "download"
+  ],
+  "author": "Justin R. Hall <justin.r.hall@gmail.com>",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "add-icon": "bin/add-icon.js"
+  },
+  "files": [
+    "dist",
+    "bin"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "del-cli dist",
+    "prebuild": "npm run --silent clean",
+    "prepublishOnly": "run-p --silent lint typecheck build",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "typecheck": "attw --pack --profile esm-only",
+    "lint": "eslint --cache --cache-location ./node_modules/.cache/eslint .",
+    "format": "prettier --cache --write .",
+    "format:check": "prettier --cache --check .",
+    "changeset": "changeset",
+    "changeset:version": "changeset version && npm install --package-lock-only",
+    "changeset:publish": "changeset publish"
+  },
+  "prettier": "@wkovacs64/prettier-config",
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "dependencies": {
+    "commander": "^13.1.0",
+    "esbuild": "~0.25.2",
+    "typescript": "^5.8.3"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "0.17.4",
+    "@changesets/changelog-github": "0.5.1",
+    "@changesets/cli": "2.29.0",
+    "@types/node": "22.14.1",
+    "@wkovacs64/eslint-config": "7.5.2",
+    "@wkovacs64/prettier-config": "4.1.1",
+    "del-cli": "6.0.0",
+    "eslint": "9.24.0",
+    "npm-run-all2": "7.0.2",
+    "prettier": "3.5.3",
+    "tsx": "4.19.3"
+  }
+}