Scribunto Bundler

Common errors

• SyntaxError: Cannot use import statement outside a module

  cause The `bundler.config.js` uses `export default` (ESM syntax) but Node.js is trying to parse it as a CommonJS module.
  fix Add `"type": "module"` to your project's `package.json` or rename `bundler.config.js` to `bundler.config.mjs`.

• Error: Main file 'src/main.lua' not found. Please check your 'main' configuration.

  cause The `main` property in `bundler.config.js` points to a Lua file that does not exist at the specified path relative to the project root.
  fix Verify the path specified in `config.main` within your `bundler.config.js` is correct and the file exists at that location.

• Error: Could not resolve module 'myModule' in 'src/main.lua' (or similar resolution error)

  cause A `require()` statement in a Lua file refers to a module that `scribunto-bundler` cannot locate within the project's defined module resolution paths.
  fix Ensure that all Lua modules referenced by `require()` statements are placed in directories where `scribunto-bundler` can find them. Typically, this means they should be in the same directory as the requiring file or in subdirectories that follow Lua's module search path conventions, relative to the configured `main` file. Check module filenames and extensions (`.lua` or `.luau`).

Warnings

• breaking The 0.2.0 release was explicitly marked as 'Most likely a very unstable version' during its release cycle. Users upgrading from 0.1.x to 0.2.x should anticipate potential breaking changes in configuration or API. The changelog does not provide granular details on specific breaking points, indicating a significant internal overhaul or shift in development focus.
  Fix: Refer to the official GitHub repository for potential migration guides or detailed changelogs if available. It is advisable to test upgrades thoroughly in a non-production environment.
• gotcha The `bundler.config.js` file uses ECMAScript Module (ESM) syntax (`export default`). Projects configured for CommonJS in their `package.json` (e.g., no `"type"` field or `"type": "commonjs"`) might encounter `SyntaxError: Cannot use import statement outside a module` when Node.js attempts to load the configuration.
  Fix: Ensure your project's `package.json` specifies `"type": "module"` to enable ESM support, or rename your configuration file to `bundler.config.mjs` to explicitly mark it as an ES module for Node.js.
• gotcha Global installation (`npm install -g scribunto-bundler` or `pnpm add -g scribunto-bundler`) is primarily intended for initial project setup using `npx scribunto-bundler --create`. For consistent bundling within a project, it is highly recommended to install `scribunto-bundler` as a local `devDependency` (`npm install scribunto-bundler --save-dev`) and invoke it via `npm run bundle` scripts defined in `package.json`.
  Fix: For project-specific operations, install locally as a `devDependency` and create `npm run` scripts to ensure all team members and CI/CD environments use the same bundler version and configuration.

Install

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

Imports

• Config
  wrong:

  const { Config } = require('scribunto-bundler')

  correct:

  import type { Config } from 'scribunto-bundler'

  Primarily used as a type import for `bundler.config.js` to enable type-hinting for configuration options. The library is ESM-first.
• bundle
  wrong:

  const { bundle } = require('scribunto-bundler')

  correct:

  import { bundle } from 'scribunto-bundler'

  Programmatic function to execute the bundling process, mirroring the CLI `bundle` command. Ideal for integration into custom build scripts.
• createProject
  wrong:

  const { createProject } = require('scribunto-bundler')

  correct:

  import { createProject } from 'scribunto-bundler'

  Programmatic function to scaffold a new Scribunto project, equivalent to the `npx scribunto-bundler --create` CLI command.

Quickstart

Demonstrates how to set up, configure, and perform a programmatic bundle of a basic Scribunto Lua project. It outlines both CLI setup and direct API usage for advanced scenarios.

import { bundle } from 'scribunto-bundler';
import fs from 'node:fs/promises';

// 1. Install globally for CLI, then locally for project-specific use
// npm install -g scribunto-bundler
// npx scribunto-bundler --create // Creates project and installs locally

// 2. Configure bundler.config.js (example)
/*
// bundler.config.js
/** @type {import("scribunto-bundler").Config} */
/*
export default {
  prefix: '-- Bundled by scribunto-bundler\n', // Optional prefix text
  suffix: '\n-- End of bundle', // Optional suffix text
  main: 'src/main.lua', // Path to your main Lua module
  out: 'dist/bundled.lua', // Output path for the bundled file
};
*/

// 3. Example of a programmatic bundle (alternative to `npm run bundle`)
async function runBundleProgrammatically() {
  // In a real scenario, you'd read from bundler.config.js
  const config = {
    prefix: '-- My Awesome Scribunto Module\n', // Example prefix
    suffix: '\n-- Generated: ' + new Date().toISOString(), // Example suffix
    main: 'src/main.lua', // Your main Lua file
    out: 'dist/bundled-programmatic.lua', // Output file
  };

  // Ensure source files exist for demonstration
  await fs.mkdir('src', { recursive: true });
  await fs.writeFile('src/main.lua', 'local myutil = require(\'myutil\'); return myutil.add(1, 2)');
  await fs.writeFile('src/myutil.lua', 'local M = {}; function M.add(a, b) return a + b end; return M;');

  try {
    await bundle(config);
    console.log(`Successfully bundled to ${config.out}`);
    const bundledCode = await fs.readFile(config.out, 'utf-8');
    console.log('Bundled Code:\n', bundledCode);
  } catch (error) {
    console.error('Bundling failed:', error);
  }
}

runBundleProgrammatically();