#Path Alias

Path Alias is a module import path mapping mechanism that allows developers to use short, semantic identifiers to replace complete module paths. In Esmx, the path alias mechanism provides the following advantages:

• Simplify Import Paths: Use semantic aliases to replace lengthy relative paths, improving code readability.
• Avoid Deep Nesting: Eliminate maintenance difficulties caused by multi-level directory references (like ../../../../).
• Type Safety: Fully integrated with TypeScript's type system, providing code completion and type checking.
• Module Resolution Optimization: Improve module resolution performance through predefined path mappings.

#Default Alias Mechanism

Esmx adopts an automatic alias mechanism based on Service Name. This convention-over-configuration design has the following characteristics:

• Automatic Configuration: Automatically generates aliases based on the name field in package.json, no manual configuration needed.
• Unified Specification: Ensures all service modules follow consistent naming and reference specifications.
• Type Support: Works with npm run build:dts command to automatically generate type declaration files, enabling cross-service type inference.
• Predictability: Module reference paths can be inferred through service name, reducing maintenance costs.

#Configuration Instructions

#package.json Configuration

In package.json, define the service name through the name field, which will serve as the default alias prefix for the service:

{
    "name": "your-app-name"
}

#tsconfig.json Configuration

To enable TypeScript to correctly resolve alias paths, configure paths mapping in tsconfig.json:

{
    "compilerOptions": {
        "paths": {
            "your-app-name/src/*": [
                "./src/*"
            ],
            "your-app-name/*": [
                "./*"
            ]
        }
    }
}

#Usage Examples

#Import Internal Service Modules

import { MyComponent } from 'your-app-name/src/components';
import { MyComponent as Rel } from '../components';

#Import Other Service Modules

import { SharedComponent } from 'other-service/src/components';
import { utils } from 'other-service/src/utils';

#Best Practices

#Prefer Alias Paths

In business code, alias paths should be preferred over relative paths:

import { Button } from 'your-app-name/src/components';
import { Layout } from 'your-app-name/src/components/layout';
import { formatDate } from 'your-app-name/src/utils';
import { request } from 'your-app-name/src/utils/request';
import type { UserInfo } from 'your-app-name/src/types';

#Maintain Semantics and Consistency

• Prefer alias paths over relative paths.
• Keep alias paths semantic and consistent.
• Avoid using too many directory levels in alias paths.

#Cross-Service Import

When module linking is configured, you can import modules from other services in the same way:

import { Header } from 'remote-service/src/components';
import { logger } from 'remote-service/src/utils';

#Custom Aliases

For third-party packages or special scenarios, you can customize aliases through Esmx configuration files:

import path from 'node:path';
import type { EsmxOptions } from '@esmx/core';

export default {
    async devApp(esmx) {
        return import('@esmx/rspack').then((m) =>
            m.createRspackHtmlApp(esmx, {
                chain({ chain }) {
                    chain.resolve.alias
                        .set('vue$', 'vue/dist/vue.esm.js')
                        .set('@', path.resolve('./src'))
                        .set('@components', path.resolve('./src/components'));
                }
            })
        );
    }
} satisfies EsmxOptions;