App Bundler

Common errors

• Error: Cannot find module 'atma-io' from '[path-to-your-project]'

  cause `atma-io` is a required peer dependency for `app-bundler`'s file handling and middleware system, but it has not been installed or cannot be resolved by Node.js.
  fix Ensure `atma-io` is listed in your project's `dependencies` or `devDependencies` and run `npm install` or `yarn install` to properly install it.

• SyntaxError: Unexpected token 'export' (or 'import')

  cause `app-bundler` encounters modern ES Module syntax (`import`/`export`) in your source files but does not have a configured `atma-io` middleware to transpile it to a compatible format (like CommonJS).
  fix Install and configure an `atma-io` plugin that handles JavaScript transpilation (e.g., integrating Babel) to convert ES Modules to CommonJS. Alternatively, ensure all source files use CommonJS `require()` and `module.exports` syntax.

• Error: EACCES: permission denied, open '[output-file-path]'

  cause The user account or process running `app-bundler` lacks the necessary write permissions for the specified output directory or file.
  fix Verify and adjust the file system permissions for the output directory. On Unix-like systems, ensure the user has write access. If running as a build script, check the environment permissions. As a temporary measure, `sudo npx app-bundler` might work for CLI usage, but is not recommended for automated builds.

Warnings

• breaking This package is effectively abandoned, with no significant updates or commits in over 6 years (as of 2026). It is not recommended for new projects and carries risks for existing ones due to lack of security patches, modern feature support, and community maintenance.
  Fix: Migrate to actively maintained, modern bundlers like Webpack, Rollup, Vite, or Parcel. If migration is not immediately feasible for legacy projects, understand the security and compatibility risks.
• gotcha `app-bundler` is designed for CommonJS and older web module systems (MaskJS, IncludeJS, AMD). It does not natively understand or process modern ES Modules (ESM) syntax without an external `atma-io` middleware for transpilation, requiring manual setup.
  Fix: For projects using ESM, configure a transpilation middleware (e.g., Babel via `atma-io` plugins) to convert ESM to CJS before `app-bundler` processes the files, or rewrite modules to use CommonJS `require()` syntax. Alternatively, use a modern bundler with native ESM support.
• gotcha The project emphasizes "no configuration" and "decoupled pre- and post-processing." This means advanced build features like automatic code splitting, elaborate asset optimization, or complex plugin ecosystems are not built-in to `app-bundler` itself. These require custom `atma-io` middleware development or integration with other build tools.
  Fix: For sophisticated build requirements, be prepared to develop custom `atma-io` plugins or to orchestrate `app-bundler` within a larger, multi-tool build pipeline. Assess if a more feature-rich, opinionated bundler might be more suitable for your project's needs.

Install

• npm install app-bundler npm
• yarn add app-bundler yarn
• pnpm add app-bundler pnpm

Imports

• bundle
  wrong:

  import { bundle } from 'app-bundler';

  correct:

  const { bundle } = require('app-bundler');

  This package is CommonJS-first. Its primary programmatic API is the `bundle` function, exposed via `module.exports`. ESM `import` syntax is not directly supported without a CJS wrapper or transpilation.
• CLI Execution (via child process)
  wrong:

  const cli = require('app-bundler/bin/app-bundler');

  correct:

  const { execSync } = require('child_process');
  execSync('npx app-bundler --version', { stdio: 'inherit' });

  The `bin/app-bundler` script is designed for command-line interface (CLI) execution via `npx` or a `package.json` script. Direct `require()` calls to the binary script are not intended for programmatic use and will bypass its CLI argument parsing and environment setup.
• Internal `bundle` module (discouraged)
  wrong:

  const bundlerModule = require('app-bundler/lib/bundler');
  const bundle = bundlerModule.bundle;

  correct:

  const { bundle } = require('app-bundler/lib/bundler');

  While it's technically possible to `require` internal modules like `lib/bundler.js` directly, this is generally discouraged. Internal paths are not part of the public API contract and may change in future (though unlikely for an abandoned project) without notice. Always prefer the top-level package import.

Quickstart

Demonstrates how to invoke `app-bundler` using both its command-line interface via `npx` for a `package.json` script and a programmatic approach using its exported `bundle` function for a CommonJS application.

/* package.json example for basic CLI bundling:
"scripts": {
  "build": "app-bundler --entry src/main.js --output dist/app.bundle.js"
}
*/

// CLI Usage Example (run in your project's root):
// npx app-bundler --entry src/main.js --output dist/app.bundle.js

// Programmatic Usage Example:
const { bundle } = require('app-bundler');
const path = require('path');
const fs = require('fs');

async function buildApplication() {
  const sourceDirectory = path.resolve(__dirname, 'src');
  const outputDirectory = path.resolve(__dirname, 'dist');
  const entryFilePath = path.join(sourceDirectory, 'main.js');
  const outputFilePath = path.join(outputDirectory, 'app.bundle.js');

  // Ensure the output directory exists
  if (!fs.existsSync(outputDirectory)) {
    fs.mkdirSync(outputDirectory, { recursive: true });
  }

  try {
    console.log('Starting application bundling with app-bundler...');
    // The `bundle` function's exact API is not explicitly detailed in the README.
    // Based on CLI arguments, a simple object might be accepted.
    // For production, refer to the source code for precise options.
    await bundle({
      input: entryFilePath,
      output: outputFilePath,
      type: 'commonjs' // Specify the module type, e.g., 'commonjs', 'amd', 'maskjs'
      // Other options might include 'includejsPaths' or preprocessor configurations
    });
    console.log(`Bundling completed successfully to: ${outputFilePath}`);
  } catch (error) {
    console.error('Application bundling failed:', error);
    process.exit(1);
  }
}

// Uncomment to run the programmatic build (e.g., as part of a custom build script)
// buildApplication();