StealJS Build Tools

Common errors

• Error: `stealTools.build` is not a function

  cause Attempting to use `stealTools.build` after incorrectly importing `steal-tools` using named ESM imports, or trying to access a non-existent property.
  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()`.

• Error: Minification failed: 'foo' is not defined

  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.
  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.

• SyntaxError: Unexpected token '`' (or other ES2015+ features)

  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).
  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.

• ReferenceError: steal is not defined (when running the built application)

  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.
  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.

Warnings

• breaking 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.
  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.
• gotcha 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.
  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.
• breaking 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.
  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.
• gotcha 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.
  Fix: Upgrade to `steal-tools@2.2.1` or newer to incorporate the fix for `rollup-plugin-commonjs`.
• breaking 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.
  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.

Install

• npm install steal-tools npm
• yarn add steal-tools yarn
• pnpm add steal-tools pnpm

Imports

• stealTools
  wrong:

  import { stealTools } from 'steal-tools';

  correct:

  const stealTools = require('steal-tools');

  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.
• build
  wrong:

  import { build } from 'steal-tools';

  correct:

  const stealTools = require('steal-tools');
  stealTools.build(config, options);

  The `build` function is a method of the default `stealTools` export, not a top-level named export. It is accessed as `stealTools.build()`.
• streams
  wrong:

  import { streams } from 'steal-tools';

  correct:

  const { streams } = require('steal-tools');
  const graphStream = streams.graph({ config: './package.json!npm' });

  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.

Quickstart

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.

const stealTools = require('steal-tools');
const path = require('path');

const projectRoot = path.resolve(__dirname, 'my-steal-app');
const outputPath = path.resolve(projectRoot, 'dist');

console.log('Starting StealJS application build...');

stealTools.build({
  // Configuration for your StealJS app
  config: path.join(projectRoot, 'package.json!npm'), // Path to your package.json with StealJS config
  main: 'my-app/main' // Your main application module
}, {
  // Build options
  minify: true, // Minify the output code (default: true)
  bundleAssets: true, // Bundle assets like CSS/images
  dest: outputPath, // Destination folder for the build
  removeDevelopmentCode: true, // Remove development-specific code
  verbose: true // Log more details about the build process
}).then(function(buildResult) {
  console.log('StealJS application build complete!');
  console.log(`Output written to: ${outputPath}`);
  // You can inspect buildResult for more details like bundles, graph, etc.
  // For example: console.log(buildResult.bundles);
}).catch(function(err) {
  console.error('StealJS build failed:', err);
  process.exit(1);
});