{"id":16227,"library":"steal-tools","title":"StealJS Build Tools","description":"Steal-tools is a robust collection of command-line and programmatic utilities designed for building, packaging, and optimizing JavaScript applications, particularly those utilizing the StealJS module loader. It supports a wide array of module formats including ES6 Modules, CommonJS, and AMD, facilitating the creation of applications and plugins that load efficiently. As of version 2.3.0, it leverages modern JavaScript features like dynamic `import()` via `esprima-next` and uses `terser` as its default minifier. This package is an integral part of the larger StealJS ecosystem, working in tandem with the `steal` module loader for client-side dependency management, and is actively maintained with regular patch and minor releases focusing on compatibility and feature enhancements. It differentiates itself through features like intelligent bundling, progressive loading, and comprehensive project exporting capabilities, all aimed at improving application load times and caching strategies.","status":"active","version":"2.3.0","language":"javascript","source_language":"en","source_url":"git://github.com/stealjs/steal-tools","tags":["javascript"],"install":[{"cmd":"npm install steal-tools","lang":"bash","label":"npm"},{"cmd":"yarn add steal-tools","lang":"bash","label":"yarn"},{"cmd":"pnpm add steal-tools","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"steal-tools is designed to build applications that use the StealJS module loader (package `steal`). It is explicitly stated that 'steal-tools depends on steal' and requires `steal.js` to load the app successfully in the browser before building.","package":"steal","optional":false}],"imports":[{"note":"steal-tools is primarily a CommonJS module. The main API object is typically imported via `require()`. While `import stealTools from 'steal-tools'` might work in ESM contexts due to Node.js interoperability, attempting named imports (e.g., `{ stealTools }`) is incorrect as the package exports a single object.","wrong":"import { stealTools } from 'steal-tools';","symbol":"stealTools","correct":"const stealTools = require('steal-tools');"},{"note":"The `build` function is a method of the default `stealTools` export, not a top-level named export. It is accessed as `stealTools.build()`.","wrong":"import { build } from 'steal-tools';","symbol":"build","correct":"const stealTools = require('steal-tools');\nstealTools.build(config, options);"},{"note":"The streaming API is available under the `streams` property of the main `stealTools` object. It should be destructured from the `require()` result, or accessed directly, not imported as a named export.","wrong":"import { streams } from 'steal-tools';","symbol":"streams","correct":"const { streams } = require('steal-tools');\nconst graphStream = streams.graph({ config: './package.json!npm' });"}],"quickstart":{"code":"const stealTools = require('steal-tools');\nconst path = require('path');\n\nconst projectRoot = path.resolve(__dirname, 'my-steal-app');\nconst outputPath = path.resolve(projectRoot, 'dist');\n\nconsole.log('Starting StealJS application build...');\n\nstealTools.build({\n  // Configuration for your StealJS app\n  config: path.join(projectRoot, 'package.json!npm'), // Path to your package.json with StealJS config\n  main: 'my-app/main' // Your main application module\n}, {\n  // Build options\n  minify: true, // Minify the output code (default: true)\n  bundleAssets: true, // Bundle assets like CSS/images\n  dest: outputPath, // Destination folder for the build\n  removeDevelopmentCode: true, // Remove development-specific code\n  verbose: true // Log more details about the build process\n}).then(function(buildResult) {\n  console.log('StealJS application build complete!');\n  console.log(`Output written to: ${outputPath}`);\n  // You can inspect buildResult for more details like bundles, graph, etc.\n  // For example: console.log(buildResult.bundles);\n}).catch(function(err) {\n  console.error('StealJS build failed:', err);\n  process.exit(1);\n});","lang":"javascript","description":"This quickstart demonstrates how to programmatically build a StealJS application using `steal-tools.build`. It configures a basic build, specifies entry points, enables minification and asset bundling, and sets an output directory."},"warnings":[{"fix":"Review your minification setup. If issues arise, consult `terser` documentation or consider providing a custom `minify` function in `buildOptions` to use an alternative minifier.","message":"The default minifier was changed from `uglify-es` to `terser`. While `terser` is a compatible fork, some advanced or custom minification configurations might require adjustments. Always test your build thoroughly after upgrading.","severity":"breaking","affected_versions":">=2.2.0"},{"fix":"Ensure your Node.js environment is within the supported range (10.x - 14.x) as specified in the `engines` field of the `package.json`. Use a tool like `nvm` to manage Node.js versions.","message":"Node.js version compatibility is critical. `steal-tools` officially supports Node.js 10.x to 14.x. Using unsupported or newer Node.js versions may lead to unexpected build failures due to breaking changes in Node.js itself or incompatible dependencies.","severity":"gotcha","affected_versions":"all"},{"fix":"If encountering transpilation errors with modern JavaScript, ensure `forceES5` is set correctly in your build configuration. If you intend to preserve ES2015+ syntax, explicitly set `forceES5: false`. Update to `>=2.2.3` to resolve `estraverse`-related parsing issues.","message":"Introduced `forceES5` flag to skip ES2015 transpilation. Previously, there were issues with builds where source code used ES2015 features (like template literals) and `forceES5` was implicitly false. An old `estraverse` version caused parsing failures.","severity":"breaking","affected_versions":">=2.2.3"},{"fix":"Upgrade to `steal-tools@2.2.1` or newer to incorporate the fix for `rollup-plugin-commonjs`.","message":"Version 2.2.1 updated the `rollup-plugin-commonjs` semver range to avoid a buggy version. Older versions might experience build issues related to CommonJS module bundling.","severity":"gotcha","affected_versions":"<2.2.1"},{"fix":"Review your codebase for non-standard or highly experimental JavaScript syntax. No specific fix is usually needed, but be aware of the parser update if encountering new syntax errors.","message":"The update to `esprima-next` parser (v2.3.0) unlocks support for later ECMAScript features like dynamic `import()`. While this is generally an improvement, it could theoretically expose new parsing behaviors or stricter adherence to specs for previously lenient syntax.","severity":"breaking","affected_versions":">=2.3.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure `steal-tools` is imported as a CommonJS module using `const stealTools = require('steal-tools');` or as a default ESM import `import stealTools from 'steal-tools';` and then access the `build` method as `stealTools.build()`.","cause":"Attempting to use `stealTools.build` after incorrectly importing `steal-tools` using named ESM imports, or trying to access a non-existent property.","error":"Error: `stealTools.build` is not a function"},{"fix":"Check the code causing the error for syntax that might be unsupported by `terser` or aggressive minification. Adjust `buildOptions.minify` (e.g., set to `false` temporarily, or provide a custom minifier function) or refer to `terser`'s documentation for compatible syntax.","cause":"Minification errors after upgrading to `steal-tools@2.2.0+` due to the switch from `uglify-es` to `terser`, which might have different parsing or optimization rules, especially for non-standard JavaScript.","error":"Error: Minification failed: 'foo' is not defined"},{"fix":"Ensure `forceES5` is set to `false` in your `stealTools.build` options if you want to preserve ES2015+ syntax. Upgrade `steal-tools` to version `>=2.2.3` to fix issues with `estraverse` not supporting modern AST nodes.","cause":"Attempting to build an application with modern JavaScript (e.g., template literals, arrow functions) while `steal-tools` is configured to transpile to an older ES version, possibly due to `forceES5` being `true` or an outdated transpiler. This was a known bug in older versions (<2.2.3).","error":"SyntaxError: Unexpected token '`' (or other ES2015+ features)"},{"fix":"Ensure `bundleSteal: true` is included in your `stealTools.build` options if you want `steal.js` to be part of your main bundle. Alternatively, if `bundleSteal` is `false`, ensure `steal.js` is loaded separately in your HTML before your application's bundles.","cause":"The built application relies on the `steal` module loader, but it was not correctly bundled or is not available in the runtime environment. This often happens if `bundleSteal: false` is set in build options, or if `steal` itself is not properly configured.","error":"ReferenceError: steal is not defined (when running the built application)"}],"ecosystem":"npm"}