Makage Build Helper

0.3.0 · active · verified Sun Apr 19

Makage is a lightweight, cross-platform build helper specifically designed for managing common tasks within monorepo environments. Currently at version 0.3.0, it provides essential utilities for file operations such as copying files, cleaning directories, and general asset management. Its primary focus is on simplifying build processes across different operating systems, offering a more streamlined alternative to platform-specific scripts or heavier build tools. Given its pre-1.0 version, the release cadence is likely irregular, with features and API potentially evolving rapidly. Key differentiators include its 'tiny' footprint and explicit support for monorepo structures, aiming to minimize configuration overhead for common build-related file manipulations. It ships with TypeScript types, facilitating its integration into modern TypeScript-based projects.

Common errors

```
Error: Command 'makage' not found
```
cause The `makage` CLI tool is not installed globally or is not in the system's PATH.

fix Install Makage globally using `npm install -g makage` or run it locally via `npx makage` or `yarn makage` if installed as a dev dependency.
```
Error: ENOENT: no such file or directory, stat '/path/to/nonexistent/source'
```
cause A `copy` or `clean` operation was attempted on a source file/directory that does not exist.

fix Verify that the source paths provided to Makage's functions or CLI commands are correct and that the files/directories exist before the operation is executed. Add path validation if necessary.
```
TypeError: Cannot read properties of undefined (reading 'copy')
```
cause Attempting to `require()` Makage functions in a CommonJS module when the package's main entry point is ESM-first, or using incorrect named imports.

fix For CommonJS, ensure `type: 'module'` is not set in `package.json` or switch to dynamic `import()` if the package is truly ESM-only. For ESM, use `import { copy } from 'makage';`. Always confirm the package's module type and export patterns.

Warnings

breaking As a pre-1.0 package (v0.3.0), Makage does not strictly adhere to semantic versioning. Minor or patch releases may introduce breaking API changes without prior deprecation warnings.
Fix: Always review the release notes and changelog when upgrading Makage within the 0.x series. Pin exact versions in `package.json` to prevent unexpected breaking changes.
gotcha Cross-platform file path nuances (e.g., backslashes vs. forward slashes) can cause issues. While Makage aims for cross-platform compatibility, always test build scripts on all target operating systems.
Fix: Use Node.js's `path` module (`path.join`, `path.resolve`) for constructing file paths to ensure correct formatting across different OS environments. Avoid hardcoding path separators.
gotcha File operation permissions can lead to `EACCES` or `EPERM` errors, especially when writing to protected directories or attempting to clean files opened by another process.
Fix: Ensure the build process runs with appropriate user permissions. On Windows, temporary locking of files can often be resolved by retrying the operation or ensuring no other processes are accessing the target files. Use `fs-extra` or similar for more robust file ops if Makage's internal handling proves insufficient for edge cases.

Install

npm install makage npm
yarn add makage yarn
pnpm add makage pnpm

Imports

copy
wrong:
```
const { copy } = require('makage');
```
correct:
```
import { copy } from 'makage';
```
Makage primarily targets modern Node.js environments and ships with ESM support. While CJS might work via transpilation, direct ESM imports are recommended for consistency and type safety.
clean
wrong:
```
import clean from 'makage/clean';
```
correct:
```
import { clean } from 'makage';
```
Individual utility functions like 'clean' are exposed as named exports. Avoid importing from subpaths unless explicitly documented, as internal paths are subject to change.
runCLI
wrong:
```
import { MakageCLI } from 'makage';
```
correct:
```
import { runCLI } from 'makage/cli';
```
For advanced programmatic control of the CLI, the 'runCLI' function can be imported, typically from a dedicated 'cli' subpath. This is less common for typical usage where the CLI is executed directly.

Quickstart

This quickstart demonstrates programmatic usage of Makage to clean a 'dist' directory and copy 'assets' from 'src' to 'dist', simulating a basic build pipeline. It highlights how to import and use the `clean` and `copy` utilities.

import { copy, clean } from 'makage';
import * as path from 'path';

const projectRoot = process.cwd();
const distDir = path.join(projectRoot, 'dist');
const assetsSrc = path.join(projectRoot, 'src', 'assets');
const assetsDest = path.join(distDir, 'assets');

async function buildPackage() {
  console.log('Starting build...');
  try {
    // Clean the distribution directory
    console.log(`Cleaning ${distDir}...`);
    await clean(distDir);
    console.log('Clean complete.');

    // Copy assets
    console.log(`Copying assets from ${assetsSrc} to ${assetsDest}...`);
    await copy(assetsSrc, assetsDest, { overwrite: true, recursive: true });
    console.log('Asset copy complete.');

    // Simulate other build steps (e.g., transpilation)
    console.log('Running other build steps (e.g., TypeScript compilation)...');
    await new Promise(resolve => setTimeout(resolve, 500)); // Placeholder for actual build logic

    console.log('Build successful!');
  } catch (error) {
    console.error('Build failed:', error);
    process.exit(1);
  }
}

buildPackage();

view raw JSON →