Rucksack Lite Resource Management Core

Common errors

• ERR_REQUIRE_ESM

  cause Attempting to import `rucksack-lite` using `require()` in a CommonJS module, but the package is an ES Module.
  fix Convert your module to ES Modules (e.g., use `import` syntax, ensure `"type": "module"` in package.json, or use `.mjs` file extension). Alternatively, use dynamic import: `const { default: RucksackLite } = await import('rucksack-lite');`

• TypeError: RucksackLite is not a constructor

  cause Incorrectly importing `RucksackLite` (e.g., using named import `import { RucksackLite } from 'rucksack-lite'`) when it is a default export.
  fix Use the default import syntax: `import RucksackLite from 'rucksack-lite';`

• Error: bundle_dir is not defined or is not an absolute path

  cause The `bundle_dir` option passed to `RucksackLite` constructor is either missing or provided as a relative path, which can cause issues with file operations or later bundling steps.
  fix Ensure `bundle_dir` is always an absolute path. Use Node.js built-in `path.resolve(__dirname, 'your_directory')` or similar methods to construct an absolute path.

Warnings

• breaking Version 6.0.0 introduces a complete rewrite of the library, potentially breaking existing integrations. Key changes include a refined resource class and updated handling of local/remote resources.
  Fix: Review the updated API documentation, especially for resource addition (`add`) and initialization (`RucksackLite` constructor), and adapt code accordingly. The example uses ESM syntax with `import.meta.url`.
• breaking The package transitioned to an ESM-only module, indicated by the use of `import` statements and `import.meta.url` in examples. CommonJS `require()` is no longer supported directly for synchronous imports.
  Fix: Migrate your project to use ES Modules (e.g., use `import` syntax, ensure `"type": "module"` in package.json, or use `.mjs` file extension). Alternatively, use dynamic import: `const { default: RucksackLite } = await import('rucksack-lite');` in a CommonJS context.
• breaking Version 3.0.0 relicensed the project under The KINDLY License. While this might not be a direct API breaking change, it represents a significant change in usage terms and conditions which may require review by legal or compliance teams.
  Fix: Review The KINDLY License terms available on the project's GitHub repository to ensure compatibility with your project's licensing and usage policies.
• gotcha `rucksack-lite` focuses solely on resource management, path resolution, and HTML markup generation. It does not perform actual JavaScript or CSS file bundling, minification, or concatenation. For bundling, the separate `rucksack` package is required.
  Fix: Ensure you are using `rucksack` for actual bundling operations. `rucksack-lite` provides the resource abstraction layer. Do not expect `rucksack-lite.bundle()` to create minified or concatenated files without additional setup or the full `rucksack` package.

Install

• npm install rucksack-lite npm
• yarn add rucksack-lite yarn
• pnpm add rucksack-lite pnpm

Imports

• RucksackLite
  wrong:

  const RucksackLite = require('rucksack-lite')

  correct:

  import RucksackLite from 'rucksack-lite'

  RucksackLite is the default export and the main class. The package is ESM-only since v6.
• RucksackResource
  wrong:

  import RucksackResource from 'rucksack-lite/lib/RucksackResource'

  correct:

  import { RucksackResource } from 'rucksack-lite'

  RucksackResource is a class for defining individual assets; it's documented as a constructor and likely a named export from the main module.
• Dynamic Import

  const { default: RucksackLite } = await import('rucksack-lite');

  For environments requiring dynamic loading or specific module resolution, RucksackLite can be imported asynchronously in both ESM and CJS contexts.

Quickstart

This quickstart demonstrates how to instantiate `RucksackLite`, add various types of resources (remote JS by string, remote CSS explicitly via `RucksackResource`), and generate the corresponding HTML markup. It highlights the resource management capabilities without performing actual file bundling, which is the domain of the `rucksack` package.

import RucksackLite, { RucksackResource } from 'rucksack-lite';
import path from 'path';
import { fileURLToPath } from 'url';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

async function setupRucksack() {
  const r = new RucksackLite({
    name: "my-app",
    bundle_dir: path.resolve(__dirname, "output"), // Ensure an absolute path for bundle_dir
    bundle_url: "/static",
    input: "main.js" // This input file isn't created in this example, but defines the primary bundle.
  });

  // Add a remote JavaScript resource by URL string
  r.add("https://example.com/index.js");

  // Add a remote CSS resource using the RucksackResource class for explicit typing
  r.add(new RucksackResource({
    path: "https://example.com/styles.css",
    type: "css"
  }));

  // Generate the HTML markup (note: this does not perform actual bundling)
  const htmlMarkup = r.html();
  console.log('Generated HTML Markup:\n', htmlMarkup);

  // The `bundle()` method primarily processes local resources for path resolution
  // It does NOT create actual bundled files without the full `rucksack` package and actual files.
  try {
    console.log('\nAttempting to call bundle() (no actual files created in this quickstart):');
    await r.bundle();
    console.log('Bundle operation completed (paths resolved, if any local resources were added).');
  } catch (error) {
    console.warn('Bundle operation warning (expected without actual files/bundler):', error.message);
  }

  console.log('\nRefreshed Markup after potential bundle operation:');
  console.log(r.html());
}

setupRucksack().catch(console.error);