alias-to-config-plugin

English | 中文

Automatically generate jsconfig.json/tsconfig.json path mappings from Webpack/Vite alias configurations.

🎯 Features

• Auto-sync aliases: Automatically converts Webpack/Vite alias configurations to jsconfig.json/tsconfig.json path mappings
• Smart detection: Intelligently detects whether to use jsconfig.json or tsconfig.json
• Multiple formats support: Compatible with Webpack object format, Vite object format, and Vite array format
• Flexible filtering: Support for excluding specific aliases or paths using regex patterns
• Performance optimized: Skip file writes when configuration hasn't changed
• TypeScript ready: Full TypeScript support with comprehensive type definitions
• Zero config: Works out of the box with sensible defaults

📦 Installation

npm install alias-to-config-plugin --save-dev

Or using yarn:

yarn add alias-to-config-plugin --dev

Or using pnpm:

pnpm add alias-to-config-plugin --dev

🚀 Usage

Import Methods

You can import the plugins using different methods:

Method 1: Named Import (Recommended)

import {
  ViteAliasToConfigPlugin,
  WebpackAliasToConfigPlugin,
} from "alias-to-config-plugin";

Method 2: Subpath Import

// For Vite
import ViteAliasToConfigPlugin from "alias-to-config-plugin/vite";

// For Webpack
import WebpackAliasToConfigPlugin from "alias-to-config-plugin/webpack";

Method 3: CommonJS (Webpack)

const { WebpackAliasToConfigPlugin } = require("alias-to-config-plugin");
// or
const WebpackAliasToConfigPlugin = require("alias-to-config-plugin/webpack");

Vite Plugin

// vite.config.js
import { defineConfig } from "vite";
import createAliasToConfigPlugin from "alias-to-config-plugin/vite";

export default defineConfig({
  plugins: [
    createAliasToConfigPlugin({
      // Optional: custom jsconfig.json path
      configPath: "./jsconfig.json",
      // Optional: custom baseUrl
      baseUrl: ".",
      // Optional: exclude specific aliases
      excludeAlias: ["@test", "@mock"],
      // Optional: exclude aliases matching regex
      excludeAliasReg: /^@test/,
      // Optional: exclude paths matching regex
      excludeAliasPathReg: /node_modules/,
    }),
  ],
  resolve: {
    alias: {
      "@": "./src",
      "@components": "./src/components",
      "@utils": "./src/utils",
    },
  },
});

Webpack Plugin

// webpack.config.js
const { WebpackAliasToConfigPlugin } = require("alias-to-config-plugin");

module.exports = {
  plugins: [
    new WebpackAliasToConfigPlugin({
      configPath: "./jsconfig.json",
      baseUrl: ".",
    }),
  ],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "src"),
      "@components": path.resolve(__dirname, "src/components"),
    },
  },
};

Standalone Usage

import ConfigGenerator from "alias-to-config-plugin/configGenerator";

const generator = new ConfigGenerator({
  configPath: "./jsconfig.json",
  baseUrl: ".",
});

// Generate config from alias object
generator.generateConfig({
  "@": "./src",
  "@components": "./src/components",
});

📋 Configuration Options

| Option | Type | Default | Description | | --------------------- | ---------- | ------------- | ----------------------------------------------------- | | enable | boolean | true | Enable/disable the plugin | | configPath | string | Auto-detected | Path to jsconfig.json or tsconfig.json | | baseUrl | string | "." | Base URL for path resolution | | excludeAlias | string[] | [] | Array of alias names to exclude | | excludeAliasReg | RegExp | null | Regex pattern to exclude aliases | | excludeAliasPathReg | RegExp | null | Regex pattern to exclude paths |

🔧 How It Works

1. Detection: Automatically detects whether to use jsconfig.json or tsconfig.json
2. Normalization: Converts various alias formats (Webpack object, Vite object/array) to a unified format
3. Path Mapping: Transforms aliases into jsconfig/tsconfig path mappings
4. Smart Merging: Merges with existing configuration, preserving user settings
5. Optimization: Skips file writes when configuration hasn't changed

💡 Examples

Input Alias Configuration

// Vite/Webpack alias
{
  '@': './src',
  '@components': './src/components',
  '@utils': './src/utils',
  '@assets': './src/assets'
}

Generated jsconfig.json

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@": ["./src"],
      "@/*": ["./src/*"],
      "@components": ["./src/components"],
      "@components/*": ["./src/components/*"],
      "@utils": ["./src/utils"],
      "@utils/*": ["./src/utils/*"],
      "@assets": ["./src/assets"],
      "@assets/*": ["./src/assets/*"]
    }
  }
}

🎨 Advanced Usage

Excluding Specific Aliases

ViteAliasToConfigPlugin({
  excludeAlias: ["@test", "@mock"],
  excludeAliasReg: /^@(test|mock)/,
  excludeAliasPathReg: /node_modules/,
});

🔗 Compatibility

• Node.js: >= 14.0.0

📊 Performance

• Fast: Optimized for large codebases with 1500+ aliases
• Efficient: Skip unnecessary file writes
• Memory-friendly: Minimal memory footprint

🧪 Testing

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run performance tests
npm run test:run

📄 License

MIT License

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📞 Support

If you have any questions or issues, please open an issue on GitHub.