{"id":14692,"library":"makage","title":"Makage Build Helper","description":"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.","status":"active","version":"0.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/hyperweb-io/makage","tags":["javascript","build","copy","clean","cli","cross-platform","monorepo","package-management","typescript"],"install":[{"cmd":"npm install makage","lang":"bash","label":"npm"},{"cmd":"yarn add makage","lang":"bash","label":"yarn"},{"cmd":"pnpm add makage","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { copy } = require('makage');","symbol":"copy","correct":"import { copy } from 'makage';"},{"note":"Individual utility functions like 'clean' are exposed as named exports. Avoid importing from subpaths unless explicitly documented, as internal paths are subject to change.","wrong":"import clean from 'makage/clean';","symbol":"clean","correct":"import { clean } from 'makage';"},{"note":"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.","wrong":"import { MakageCLI } from 'makage';","symbol":"runCLI","correct":"import { runCLI } from 'makage/cli';"}],"quickstart":{"code":"import { copy, clean } from 'makage';\nimport * as path from 'path';\n\nconst projectRoot = process.cwd();\nconst distDir = path.join(projectRoot, 'dist');\nconst assetsSrc = path.join(projectRoot, 'src', 'assets');\nconst assetsDest = path.join(distDir, 'assets');\n\nasync function buildPackage() {\n  console.log('Starting build...');\n  try {\n    // Clean the distribution directory\n    console.log(`Cleaning ${distDir}...`);\n    await clean(distDir);\n    console.log('Clean complete.');\n\n    // Copy assets\n    console.log(`Copying assets from ${assetsSrc} to ${assetsDest}...`);\n    await copy(assetsSrc, assetsDest, { overwrite: true, recursive: true });\n    console.log('Asset copy complete.');\n\n    // Simulate other build steps (e.g., transpilation)\n    console.log('Running other build steps (e.g., TypeScript compilation)...');\n    await new Promise(resolve => setTimeout(resolve, 500)); // Placeholder for actual build logic\n\n    console.log('Build successful!');\n  } catch (error) {\n    console.error('Build failed:', error);\n    process.exit(1);\n  }\n}\n\nbuildPackage();","lang":"typescript","description":"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."},"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.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The `makage` CLI tool is not installed globally or is not in the system's PATH.","error":"Error: Command 'makage' not found"},{"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.","cause":"A `copy` or `clean` operation was attempted on a source file/directory that does not exist.","error":"Error: ENOENT: no such file or directory, stat '/path/to/nonexistent/source'"},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'copy')"}],"ecosystem":"npm"}