Macross Bundler

0.1.24 verified Thu Apr 23 auth: no javascript

Macross Bundler is a set of managed Webpack configuration scripts designed to simplify the build process for web applications. It abstracts away complex Webpack setups, providing a streamlined command-line interface for common tasks like starting a development server and building for production. The current stable version is 0.1.24, indicating it's still in early development, and API changes can be expected. Its primary differentiator lies in providing a highly opinionated and managed configuration experience, similar to tools like Create React App but with custom extensions, notably including specific configurations for CDN prefixes and backend proxies, which may suggest an origin or strong influence from enterprise environments like Rakuten. It requires Node.js >= 16 and has peer dependencies on Webpack >= 5 and React >= 16.

Common errors

error sh: macross-bundler: command not found ↓

cause The `macross-bundler` executable is not in the system's PATH or your `package.json` scripts are incorrectly configured, or `npm install` was not run.

fix

Ensure macross-bundler is installed as a devDependency (npm install --save-dev macross-bundler), and that your package.json scripts call macross-bundler directly or via npx (e.g., "start": "macross-bundler start"). Always run npm install after cloning a project.

error Error: Cannot find module 'webpack' or 'react' ↓

cause Despite being a peer dependency, `webpack` or `react` might not be directly installed in your project, or the installed version does not meet the `macross-bundler`'s requirements.

fix

Explicitly install the required peer dependencies: npm install webpack@^5 react@^16.

error ERR_MODULE_NOT_FOUND in macross.config.js ↓

cause This typically occurs when Node.js is trying to interpret `macross.config.js` as a CommonJS module, but it uses ESM `export default` syntax.

fix

Ensure your macross.config.js file uses export default. If your package.json does not have "type": "module", consider renaming macross.config.js to macross.config.mjs to force ESM interpretation.

Warnings

breaking As a 0.1.x version package, the API of `macross-bundler` is highly unstable and subject to frequent breaking changes without prior major version increments. Relying on specific internal behaviors or undocumented features is risky. ↓

fix Always pin to exact patch versions (`~0.1.x`) and thoroughly review release notes for each update. Be prepared for manual migration of configurations or scripts.

gotcha The `macross.config.js` file is expected to use ESM syntax (`export default`). Attempting to use CommonJS (`module.exports = {}`) will result in module resolution errors. ↓

fix Ensure `macross.config.js` uses `export default`. If your project's `package.json` `type` is set to `commonjs`, or if you are in a legacy Node.js environment, you might need to rename the config file to `macross.config.mjs`.

gotcha Macross Bundler has strict peer dependencies on `webpack` (>= 5) and `react` (>= 16). Mismatched versions will lead to installation warnings or runtime errors during the build process. ↓

fix Ensure your project explicitly installs compatible versions of `webpack` and `react`. Use `npm install webpack@^5 react@^16` to satisfy these requirements.

gotcha Configuration options like `cdnPrefixUrl` and `backendProxy` suggest an opinionated setup potentially tailored for specific enterprise environments (e.g., Rakuten). These might not be applicable or require careful customization for general-purpose projects. ↓

fix Review all configuration options in `macross.config.js` carefully. Customize `cdnPrefixUrl`, `backendProxy`, and other environment-specific settings to match your project's infrastructure, or remove them if not needed.

Install

npm install macross-bundler

yarn add macross-bundler

pnpm add macross-bundler

Imports

macross-bundler CLI commands

wrong

import { start } from 'macross-bundler'; // Not an exposed JS API
const { build } = require('macross-bundler'); // Not an exposed JS API

correct

npx create-macross-app my-app
# or use in package.json scripts:
// "start": "macross-bundler start"
// "build": "macross-bundler build"

Macross Bundler is primarily a command-line interface (CLI) tool. Its core functionality is invoked via `npx` or `package.json` scripts, not by direct programmatic JavaScript imports.

Macross Configuration Object

wrong

import MacrossConfig from 'macross-bundler/config'; // Config is exported from your local file, not imported from the package
const config = require('./macross.config.js'); // Use 'import' for ESM config files.

correct

// macross.config.js
export default {
  entries: { 'index': './src/index.js' },
  publicDir: './templates',
  // ... other config options
};

The configuration is defined in a local `macross.config.js` file which uses ESM `export default`. The bundler then consumes this file. It's not a symbol imported from the `macross-bundler` package itself, but rather a file that exports configuration *to* the bundler.

MacrossConfig (Type Definition)
wrong
```
import { MacrossConfig } from 'macross-bundler'; // Use 'import type' for type-only imports.
```
correct
```
import type { MacrossConfig } from 'macross-bundler';
```
If the library provides TypeScript type definitions for its configuration, developers can import the `MacrossConfig` type for type-checking their `macross.config.js` file. This is the most likely valid programmatic import.

Quickstart

Demonstrates initializing a new project using `create-macross-app`, configuring `macross.config.js`, installing dependencies, and starting the development server.

npx create-macross-app my-app
cd my-app
npm install

// macross.config.js (example configuration)
// This file defines how your project is built.
export default {
  entries: {
    'index': './src/index.js',
  },
  publicDir: './templates',
  outDir: '../resources/static',
  templateOurDir: '../resources/templates',
  cdnPrefixUrl: 'https://cdn.example.com', // Customize for your CDN
  backendProxy: 'http://localhost:3000', // Proxy API requests in dev
  devServerPort: 1234,
};

npm run start
// Open your browser to http://localhost:1234