Skypager Bundler Helpers

Common errors

• Error: Cannot find module 'webpack' or its corresponding type declarations.

  cause Webpack is a peer dependency and must be installed separately.
  fix Install Webpack in your project: `npm install webpack webpack-cli --save-dev` or `yarn add webpack webpack-cli --dev`.

• TypeError: runtime.use is not a function or is deprecated for this type of helper.

  cause The API for registering helpers with the Skypager runtime may have changed in newer versions, or the helper expects different initialization arguments.
  fix Consult the latest Skypager documentation for the correct `runtime.use` signature and ensure you are passing the `Bundler` class and its options correctly. The `name` option is crucial for helper registration.

• Module not found: Error: Can't resolve './src/index.js' in '...' during build.

  cause The specified entry point for Webpack (`options.entry`) does not exist or is incorrect relative to the project root.
  fix Verify the `entry` path in your bundler configuration. Ensure the file exists and the path is resolved correctly, potentially using `path.resolve(projectRoot, 'your/entry/file.js')`.

Warnings

• breaking Major versions of Skypager, including helpers, often introduce breaking changes to the runtime API and configuration patterns. Always consult the official Skypager monorepo changelog or specific helper documentation when upgrading across major versions (e.g., from v38 to v39). These changes can include altered `runtime.use` parameters, updated helper class constructors, or modifications to fluent API methods.
  Fix: Review the `skypager` monorepo's release notes for breaking changes relevant to `skypager-helpers-bundler`. Adjust `runtime.use()` calls and bundler configuration objects accordingly.
• gotcha The `skypager-helpers-bundler` package abstracts Webpack configuration. Directly manipulating Webpack's raw configuration objects through the 'escape hatch' `configureWebpack` can lead to unexpected behavior if not aligned with the helper's internal logic, potentially bypassing optimizations or conventions provided by the helper.
  Fix: Prioritize using the helper's fluent API and presets where possible. Use `configureWebpack` only for minor adjustments or when a feature is not exposed via the fluent API, carefully inspecting the helper's generated Webpack config before making changes.
• deprecated Older CommonJS `require()` syntax is not officially supported or recommended. The Skypager ecosystem, including its helpers, is designed for modern ES Modules (ESM) usage.
  Fix: Migrate your project to use ES module `import` statements. Ensure your `package.json` specifies `"type": "module"` or uses a transpiler like Babel configured for ESM.
• gotcha As `skypager-helpers-bundler` simplifies Webpack, it often relies on convention over configuration. Deviating significantly from default project structures or expected entry/output patterns without explicit configuration can lead to build failures.
  Fix: Ensure your project structure (e.g., `src/index.js`, `dist/bundle.js`) matches the bundler helper's expectations or explicitly define `entry` and `output` paths in your bundler configuration options.

Install

• npm install skypager-helpers-bundler npm
• yarn add skypager-helpers-bundler yarn
• pnpm add skypager-helpers-bundler pnpm

Imports

• runtime
  wrong:

  const runtime = require('skypager');

  correct:

  import runtime from 'skypager';
  import { Bundler } from 'skypager-helpers-bundler';

  Skypager is primarily designed for ES Module usage. The `Bundler` class is then typically registered with the `runtime`.
• Bundler
  wrong:

  import Bundler from 'skypager-helpers-bundler';

  correct:

  import { Bundler } from 'skypager-helpers-bundler';

  The primary Bundler Helper class is a named export. Default import is not provided or recommended.
• createWebpackConfig
  wrong:

  import { createWebpackConfig } from 'skypager-helpers-bundler';

  correct:

  import { createWebpackConfig } from 'skypager-helpers-bundler/util';

  Utility functions for direct configuration creation might be in sub-paths, distinct from the main Helper class.

Quickstart

This quickstart demonstrates initializing the Skypager runtime and registering a `Bundler` helper to configure Webpack for a project, including entry, output, and custom alias settings.

import runtime from 'skypager';
import { Bundler } from 'skypager-helpers-bundler';
import path from 'path';

async function setupBundler() {
  await runtime.start();
  
  const projectRoot = process.cwd();
  
  runtime.use(Bundler, { 
    name: 'my-project-bundler',
    entry: path.resolve(projectRoot, 'src/index.js'),
    output: {
      path: path.resolve(projectRoot, 'dist'),
      filename: 'bundle.js'
    },
    // Example: add a preset or custom config options
    presets: ['react-app', 'typescript'],
    configureWebpack: (config) => {
      config.resolve.alias = { '@src': path.resolve(projectRoot, 'src') };
      return config;
    }
  });

  const myBundler = runtime.feature('my-project-bundler');

  console.log('Bundler helper initialized:', myBundler.name);
  // In a real application, you would then call methods like myBundler.build() or myBundler.serve()
  // For demonstration, we just show initialization.
  console.log('Webpack entry point:', myBundler.options.entry);
  console.log('Webpack output path:', myBundler.options.output.path);
}

setupBundler().catch(console.error);