{"id":15818,"library":"scribunto-bundler","title":"Scribunto Bundler","description":"scribunto-bundler is a TypeScript-written Lua bundler specifically designed for MediaWiki's Scribunto extension. It automates the process of resolving `require` statements within Lua modules, consolidating them into a single output file suitable for deployment on MediaWiki wikis. The current stable version is 0.2.7, with the project demonstrating a rapid release cadence, frequently publishing patch and minor versions, suggesting active development and iterative improvements. Key differentiators include its explicit support for Scribunto environments, automatic `require` statement detection, and compatibility with both `.lua` and `.luau` file extensions. It offers a command-line interface for scaffolding new projects and bundling existing ones, configurable via a `bundler.config.js` file, which is type-hinted for improved developer experience.","status":"active","version":"0.2.7","language":"javascript","source_language":"en","source_url":"https://github.com/ari-party/scribunto-bundler","tags":["javascript","scribunto","lua","bundler","typescript"],"install":[{"cmd":"npm install scribunto-bundler","lang":"bash","label":"npm"},{"cmd":"yarn add scribunto-bundler","lang":"bash","label":"yarn"},{"cmd":"pnpm add scribunto-bundler","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primarily used as a type import for `bundler.config.js` to enable type-hinting for configuration options. The library is ESM-first.","wrong":"const { Config } = require('scribunto-bundler')","symbol":"Config","correct":"import type { Config } from 'scribunto-bundler'"},{"note":"Programmatic function to execute the bundling process, mirroring the CLI `bundle` command. Ideal for integration into custom build scripts.","wrong":"const { bundle } = require('scribunto-bundler')","symbol":"bundle","correct":"import { bundle } from 'scribunto-bundler'"},{"note":"Programmatic function to scaffold a new Scribunto project, equivalent to the `npx scribunto-bundler --create` CLI command.","wrong":"const { createProject } = require('scribunto-bundler')","symbol":"createProject","correct":"import { createProject } from 'scribunto-bundler'"}],"quickstart":{"code":"import { bundle } from 'scribunto-bundler';\nimport fs from 'node:fs/promises';\n\n// 1. Install globally for CLI, then locally for project-specific use\n// npm install -g scribunto-bundler\n// npx scribunto-bundler --create // Creates project and installs locally\n\n// 2. Configure bundler.config.js (example)\n/*\n// bundler.config.js\n/** @type {import(\"scribunto-bundler\").Config} */\n/*\nexport default {\n  prefix: '-- Bundled by scribunto-bundler\\n', // Optional prefix text\n  suffix: '\\n-- End of bundle', // Optional suffix text\n  main: 'src/main.lua', // Path to your main Lua module\n  out: 'dist/bundled.lua', // Output path for the bundled file\n};\n*/\n\n// 3. Example of a programmatic bundle (alternative to `npm run bundle`)\nasync function runBundleProgrammatically() {\n  // In a real scenario, you'd read from bundler.config.js\n  const config = {\n    prefix: '-- My Awesome Scribunto Module\\n', // Example prefix\n    suffix: '\\n-- Generated: ' + new Date().toISOString(), // Example suffix\n    main: 'src/main.lua', // Your main Lua file\n    out: 'dist/bundled-programmatic.lua', // Output file\n  };\n\n  // Ensure source files exist for demonstration\n  await fs.mkdir('src', { recursive: true });\n  await fs.writeFile('src/main.lua', 'local myutil = require(\\'myutil\\'); return myutil.add(1, 2)');\n  await fs.writeFile('src/myutil.lua', 'local M = {}; function M.add(a, b) return a + b end; return M;');\n\n  try {\n    await bundle(config);\n    console.log(`Successfully bundled to ${config.out}`);\n    const bundledCode = await fs.readFile(config.out, 'utf-8');\n    console.log('Bundled Code:\\n', bundledCode);\n  } catch (error) {\n    console.error('Bundling failed:', error);\n  }\n}\n\nrunBundleProgrammatically();\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.2.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"*"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Add `\"type\": \"module\"` to your project's `package.json` or rename `bundler.config.js` to `bundler.config.mjs`.","cause":"The `bundler.config.js` uses `export default` (ESM syntax) but Node.js is trying to parse it as a CommonJS module.","error":"SyntaxError: Cannot use import statement outside a module"},{"fix":"Verify the path specified in `config.main` within your `bundler.config.js` is correct and the file exists at that location.","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.","error":"Error: Main file 'src/main.lua' not found. Please check your 'main' configuration."},{"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`).","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.","error":"Error: Could not resolve module 'myModule' in 'src/main.lua' (or similar resolution error)"}],"ecosystem":"npm"}