Project Packer

A utility for packaging projects with build profile support and file filtering.

Installation

npm install project-packer

Or install globally:

npm install -g project-packer

Usage

# From the project root
project-packer [profile] [options]

# Or run directly with node
node node_modules/.bin/project-packer [profile] [options]

Examples

# Pack with the default (development) profile
project-packer

# Pack with a production profile
project-packer production

# List available profiles
project-packer --list-profiles

# Override the output format
project-packer development --format zip

# Verbose output
project-packer production --verbose

# Specify a custom project root
project-packer production --project-root /path/to/project

Configuration

• .packignore — global exclusion rules (similar to .gitignore)
• pack-config.yaml — build profiles and additional settings

Build output is saved to the packed/ directory in the project root.

Features

1. Build Profiles

Create different packaging configurations for various scenarios (development, production, extensions).

2. Profile Inheritance

Profiles can inherit settings from other profiles via the base field, avoiding configuration duplication.

3. File Filtering

• Global exclusions via .packignore
• Profile exclusions via exclude_patterns
• Forced inclusions via include_patterns (highest priority)

4. File Transformations

Modify files during packaging by executing JavaScript code. Useful for:

• Removing dependencies from package.json
• Replacing variables in configuration files
• Renaming files

5. Symlink Resolution

Automatically copies real files instead of symlinks. Solves the problem with pnpm, where node_modules contain symbolic links to inaccessible files.

6. Execution Hooks

Run commands after packing (e.g., pnpm install, pnpm build). Useful for preparing deploy-ready applications.

7. Archive Options

• Configurable compression level
• Root folder creation inside the archive for convenient extraction

8. Progress and Debugging

• Displays the currently processed directory
• Verbose mode with logging of all operations
• Error handling without interrupting the process

Configuration Example

.packignore

# Dependencies
**/node_modules/**

# Documentation
docs/**
**/*.md

# CI/CD and configuration
.gitlab-ci.yml
docker-compose.yml
.prettierrc.json

# Tests
**/*.test.*
**/*test*/**

pack-config.yaml

# General settings
output:
  base_dir: "packed"
  verbose: false

# Archive options
archive_options:
  compression_level: 9
  root_folder: "myapp"  # Creates a myapp/ folder inside the archive

# Build profiles
profiles:
  # Base production profile
  production-source:
    format: "folder"
    root_pattern: "./"
    exclude_patterns:
      - "app/src/lang/translations/**"
      - "packages/unused-driver"
      - "**/tests"
      - "**/docs"
    include_patterns:
      - "app/src/lang/translations/en-US.yaml"
    transformations:
      - pattern: "api/package.json"
        type: "json"
        operations:
          - 'delete $file.content.dependencies["some-unused-package"]'
          - '$file.content.version = "1.0.0"'

  # Inherits from production-source and adds build steps
  production-build:
    base: "production-source"
    format: "archive"
    exclude_patterns:
      - "**/scripts"
      - "**/dist"
    transformations:
      - pattern: "**/package.json"
        type: "json"
        operations:
          - 'delete $file.content.devDependencies'
    hooks:
      post_pack:
        - "pnpm install --frozen-lockfile"
        - "pnpm build"

  # Extensions only
  extensions:
    format: "folder"
    root_pattern: "./extensions"
    exclude_patterns:
      - "**/node_modules/**"
      - "**/dist/**"

  # Development profile
  development:
    format: "folder"
    root_pattern: "./"
    include_patterns:
      - "extensions/**"
    exclude_patterns:
      - "dist/**"

File Transformations

Transformations allow you to modify files during packaging:

transformations:
  - pattern: "api/package.json"
    type: "json"
    operations:
      # Remove a dependency
      - 'delete $file.content.dependencies["some-unused-package"]'
      # Change version
      - '$file.content.version = "1.0.0"'
      # Remove all dev dependencies
      - 'delete $file.content.devDependencies'

  - pattern: "**/*.env.example"
    type: "text"
    operations:
      # Replace text
      - '$file.content = $file.content.replace(/localhost:3000/g, "production.com")'
      # Rename the file
      - '$file.name = $file.name.replace(".example", "")'

The $file object contains:

• $file.content — file content (object for JSON, string for other types)
• $file.name — file name
• $file.path — relative path to the file

Profile Inheritance

Profiles can inherit settings from each other:

profiles:
  base-production:
    format: "folder"
    exclude_patterns:
      - "**/tests/**"
      - "**/docs/**"

  production-api:
    base: "base-production"
    root_pattern: "./api"
    exclude_patterns:
      - "**/node_modules/**"  # Added to base exclusions

  production-full:
    base: "production-api"
    format: "archive"  # Overrides format
    hooks:
      post_pack:
        - "pnpm build"  # Added to parent hooks

Execution Hooks

Hooks allow you to run commands after packing:

profiles:
  production:
    format: "folder"
    hooks:
      post_pack:
        - "pnpm install --frozen-lockfile"
        - "pnpm build"
        - "docker build -t myapp ."

Hooks are executed in order, and command output is displayed in real-time in the console.