Guide
API
Blog
Guide
API
Blog

PackConfig

PackConfig is the package bundling configuration interface used to package service build artifacts into standard npm .tgz format packages.

  • Standardization: Uses npm's standard .tgz packaging format
  • Completeness: Includes all necessary files such as module source code, type declarations, and configuration files
  • Compatibility: Fully compatible with the npm ecosystem, supporting standard package management workflows

Type Definition

1interface PackConfig {
2    enable?: boolean;
3    outputs?: string | string[] | boolean;
4    packageJson?: (esmx: Esmx, pkg: Record<string, any>) => Promise<Record<string, any>>;
5    onBefore?: (esmx: Esmx, pkg: Record<string, any>) => Promise<void>;
6    onAfter?: (esmx: Esmx, pkg: Record<string, any>, file: Buffer) => Promise<void>;
7}

PackConfig

enable

Whether to enable the packaging feature. When enabled, build artifacts will be packaged into standard npm .tgz format packages.

  • Type: boolean
  • Default: false

outputs

Specifies the output package file path(s). Supports the following configuration methods:

  • string: Single output path, e.g., 'dist/versions/my-app.tgz'
  • string[]: Multiple output paths for generating multiple versions simultaneously
  • boolean: When true, uses the default path 'dist/client/versions/latest.tgz'

packageJson

Callback function for customizing package.json content. Called before packaging to modify package.json content.

  • Parameters:
    • esmx: Esmx - Esmx instance
    • pkg: any - Original package.json content
  • Returns: Promise<any> - Modified package.json content

Common use cases:

  • Modifying package name and version
  • Adding or updating dependencies
  • Adding custom fields
  • Configuring publishing-related information

Example:

1packageJson: async (esmx, pkg) => {
2  // Set package information
3  pkg.name = 'my-app';
4  pkg.version = '1.0.0';
5  pkg.description = 'My Application';
6
7  // Add dependencies
8  pkg.dependencies = {
9    'vue': '^3.0.0',
10    'express': '^4.17.1'
11  };
12
13  // Add publish configuration
14  pkg.publishConfig = {
15    registry: 'https://registry.example.com'
16  };
17
18  return pkg;
19}

onBefore

Callback function for pre-packaging preparation work.

  • Parameters:
    • esmx: Esmx - Esmx instance
    • pkg: Record<string, any> - package.json content
  • Returns: Promise<void>

Common use cases:

  • Adding additional files (README, LICENSE, etc.)
  • Running tests or build validation
  • Generating documentation or metadata
  • Cleaning temporary files

Example:

1onBefore: async (esmx, pkg) => {
2  // Add documentation
3  await fs.writeFile('dist/README.md', '# My App');
4  await fs.writeFile('dist/LICENSE', 'MIT License');
5
6  // Run tests
7  await runTests();
8
9  // Generate documentation
10  await generateDocs();
11
12  // Clean temporary files
13  await cleanupTempFiles();
14}

onAfter

Callback function for post-packaging processing. Called after .tgz file generation to handle packaged artifacts.

  • Parameters:
    • esmx: Esmx - Esmx instance
    • pkg: Record<string, any> - package.json content
    • file: Buffer - Packaged file content
  • Returns: Promise<void>

Common use cases:

  • Publishing to npm registry (public or private)
  • Uploading to static asset servers
  • Performing version management
  • Triggering CI/CD pipelines

Example:

1onAfter: async (esmx, pkg, file) => {
2  // Publish to private npm registry
3  await publishToRegistry(file, {
4    registry: 'https://registry.example.com'
5  });
6
7  // Upload to static asset server
8  await uploadToServer(file, 'https://assets.example.com/packages');
9
10  // Create version tag
11  await createGitTag(pkg.version);
12
13  // Trigger deployment pipeline
14  await triggerDeploy(pkg.version);
15}

Usage Example

entry.node.ts
1import type { EsmxOptions } from '@esmx/core';
2
3export default {
4  modules: {
5    // Configure modules to export
6    exports: [
7      'root:src/components/button.vue',
8      'root:src/utils/format.ts',
9      'npm:vue',
10      'npm:vue-router'
11    ]
12  },
13  // Packaging configuration
14  pack: {
15    // Enable packaging
16    enable: true,
17
18    // Output multiple versions simultaneously
19    outputs: [
20      'dist/versions/latest.tgz',
21      'dist/versions/1.0.0.tgz'
22    ],
23
24    // Customize package.json
25    packageJson: async (esmx, pkg) => {
26      pkg.version = '1.0.0';
27      return pkg;
28    },
29
30    // Pre-packaging preparation
31    onBefore: async (esmx, pkg) => {
32      // Add necessary files
33      await fs.writeFile('dist/README.md', '# Your App\n\nModule export instructions...');
34      // Run type checking
35      await runTypeCheck();
36    },
37
38    // Post-packaging processing
39    onAfter: async (esmx, pkg, file) => {
40      // Publish to private npm registry
41      await publishToRegistry(file, {
42        registry: 'https://npm.your-registry.com/'
43      });
44      // Or deploy to static server
45      await uploadToServer(file, 'https://static.example.com/packages');
46    }
47  }
48} satisfies EsmxOptions;
ON THIS PAGE