Path Alias#

Path Alias is a module import path mapping mechanism that allows developers to use concise, semantic identifiers instead of complete module paths. In Esmx, the path alias mechanism offers the following advantages:

• Simplified Import Paths: Replace lengthy relative paths with semantic aliases to improve code readability
• Avoid Deep Nesting: Eliminate maintenance difficulties caused by multi-level directory references (e.g., ../../../../)
• 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 names (Service Name), featuring a convention-over-configuration design with the following characteristics:

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

Configuration Instructions#

package.json Configuration#

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

1{
2    "name": "your-app-name"
3}

tsconfig.json Configuration#

To ensure TypeScript correctly resolves alias paths, configure the paths mapping in tsconfig.json:

1{
2    "compilerOptions": {
3        "paths": {
4            "your-app-name/src/*": [
5                "./src/*"
6            ],
7            "your-app-name/*": [
8                "./*"
9            ]
10        }
11    }
12}

Usage Examples#

Importing Internal Service Modules#

1// Using alias import
2import { MyComponent } from 'your-app-name/src/components';
3
4// Equivalent relative path import
5import { MyComponent } from '../components';

Importing Modules from Other Services#

1// Importing components from another service
2import { SharedComponent } from 'other-service/src/components';
3
4// Importing utility functions from another service
5import { utils } from 'other-service/src/utils';

::: tip Best Practices

• Prefer alias paths over relative paths
• Maintain semantic and consistent alias paths
• Avoid excessive directory levels in alias paths :::

1// Importing components
2import { Button } from 'your-app-name/src/components';
3import { Layout } from 'your-app-name/src/components/layout';
4
5// Importing utility functions
6import { formatDate } from 'your-app-name/src/utils';
7import { request } from 'your-app-name/src/utils/request';
8
9// Importing type definitions
10import type { UserInfo } from 'your-app-name/src/types';

Cross-Service Imports#

When module linking (Module Link) is configured, modules from other services can be imported in the same way:

1// Importing components from a remote service
2import { Header } from 'remote-service/src/components';
3
4// Importing utility functions from a remote service
5import { logger } from 'remote-service/src/utils';

Custom Aliases#

For third-party packages or special scenarios, custom aliases can be defined through the Esmx configuration file:

1export default {
2    async devApp(esmx) {
3        return import('@esmx/rspack').then((m) =>
4            m.createApp(esmx, (buildContext) => {
5                buildContext.config.resolve = {
6                    ...buildContext.config.resolve,
7                    alias: {
8                        ...buildContext.config.resolve?.alias,
9                        // Configure a specific build version for Vue
10                        'vue$': 'vue/dist/vue.esm.js',
11                        // Configure short aliases for common directories
12                        '@': './src',
13                        '@components': './src/components'
14                    }
15                }
16            })
17        );
18    }
19} satisfies EsmxOptions;

::: warning Notes

1. For business modules, always use the default alias mechanism to maintain project consistency
2. Custom aliases are primarily used for handling special requirements of third-party packages or optimizing development experience
3. Excessive use of custom aliases may impact code maintainability and build optimization :::