Guide
API
Blog
Guide
API
Blog

Module Linking

The Esmx framework provides a comprehensive module linking mechanism for managing code sharing and dependency relationships between services. This mechanism is implemented based on the ESM (ECMAScript Module) specification, supporting source-level module exports/imports and complete dependency management functionality.

Core Concepts

Module Export

Module export is the process of exposing specific code units (such as components, utility functions, etc.) from a service in ESM format. Two export types are supported:

  • Source Export: Directly exports source code files from the project
  • Dependency Export: Exports third-party dependency packages used by the project

Module Linking

Module import is the process of referencing code units exported by other services. Multiple installation methods are supported:

  • Source Installation: Suitable for development environments, supports real-time modifications and hot updates
  • Package Installation: Suitable for production environments, uses build artifacts directly

Module Export

Configuration Instructions

Configure modules to be exported in entry.node.ts:

src/entry.node.ts
1import type { EsmxOptions } from '@esmx/core';
2
3export default {
4    modules: {
5        exports: [
6            // Export source files
7            'root:src/components/button.vue',  // Vue component
8            'root:src/utils/format.ts',        // Utility function
9            // Export third-party dependencies
10            'npm:vue',                         // Vue framework
11            'npm:vue-router'                   // Vue Router
12        ]
13    }
14} satisfies EsmxOptions;

Export configuration supports two types:

  • root:*: Exports source files, with paths relative to the project root
  • npm:*: Exports third-party dependencies, specified by package name directly

Module Import

Configuration Instructions

Configure modules to be imported in entry.node.ts:

src/entry.node.ts
1import type { EsmxOptions } from '@esmx/core';
2
3export default {
4    modules: {
5        // Link configuration
6        links: {
7            // Source installation: points to build output directory
8            'ssr-remote': './node_modules/ssr-remote/dist',
9            // Package installation: points to package directory
10            'other-remote': './node_modules/other-remote'
11        },
12        // Import mapping settings
13        imports: {
14            // Use dependencies from remote modules
15            'vue': 'ssr-remote/npm/vue',
16            'vue-router': 'ssr-remote/npm/vue-router'
17        }
18    }
19} satisfies EsmxOptions;

Configuration items explanation:

  1. imports: Configures local paths for remote modules

    • Source installation: Points to build output directory (dist)
    • Package installation: Directly points to package directory

  2. externals: Configures external dependencies

    • Used for sharing dependencies from remote modules
    • Avoids duplicate packaging of same dependencies
    • Supports dependency sharing across multiple modules

Installation Methods

Source Installation

Suitable for development environments, supports real-time modifications and hot updates.

  1. Workspace Method Recommended for Monorepo projects:
package.json
1{
2    "devDependencies": {
3        "ssr-remote": "workspace:*"
4    }
5}
  1. Link Method For local development and debugging:
package.json
1{
2    "devDependencies": {
3        "ssr-remote": "link:../ssr-remote"
4    }
5}

Package Installation

Suitable for production environments, uses build artifacts directly.

  1. NPM Registry Install via npm registry:
package.json
1{
2    "dependencies": {
3        "ssr-remote": "^1.0.0"
4    }
5}
  1. Static Server Install via HTTP/HTTPS protocol:
package.json
1{
2    "dependencies": {
3        "ssr-remote": "https://cdn.example.com/ssr-remote/1.0.0.tgz"
4    }
5}

Package Building

Configuration Instructions

Configure build options in entry.node.ts:

src/entry.node.ts
1import type { EsmxOptions } from '@esmx/core';
2
3export default {
4    // Module export configuration
5    modules: {
6        exports: [
7            'root:src/components/button.vue',
8            'root:src/utils/format.ts',
9            'npm:vue'
10        ]
11    },
12    // Build configuration
13    pack: {
14        // Enable building
15        enable: true,
16
17        // Output configuration
18        outputs: [
19            'dist/client/versions/latest.tgz',
20            'dist/client/versions/1.0.0.tgz'
21        ],
22
23        // Custom package.json
24        packageJson: async (esmx, pkg) => {
25            pkg.version = '1.0.0';
26            return pkg;
27        },
28
29        // Pre-build processing
30        onBefore: async (esmx, pkg) => {
31            // Generate type declarations
32            // Execute test cases
33            // Update documentation, etc.
34        },
35
36        // Post-build processing
37        onAfter: async (esmx, pkg, file) => {
38            // Upload to CDN
39            // Publish to npm registry
40            // Deploy to test environment, etc.
41        }
42    }
43} satisfies EsmxOptions;

Build Artifacts

your-app-name.tgz ├── package.json # Package information ├── index.js # Production entry ├── server/ # Server resources │ └── manifest.json # Server resource mapping ├── node/ # Node.js runtime └── client/ # Client resources └── manifest.json # Client resource mapping

Publishing Process

1# 1. Build production version
2esmx build
3
4# 2. Publish to npm
5npm publish dist/versions/your-app-name.tgz
ON THIS PAGE