Asset Mapper Test Bundle Laravel Package

Getting Started

• Add tito10047/asset-mapper-test-bundle as a dev dependency and enable it using the package’s documented Symfony bundle/Laravel provider setup. Ensure your Node test runner is installed and your AssetMapper importmap is available to the test environment.
• Look first at the package README/config for the symlink vs loader variant, your importmap.php/AssetMapper config, and the generated node_modules output. Those are the moving parts this release fixes.
• First use case: add a small test that imports a vendor package already in your importmap, e.g. @hotwired/stimulus, then run it through the bundle’s Node test setup. On 0.2.2, directory-based vendor packages with <basename>.index.js entries should resolve instead of failing with ERR_MODULE_NOT_FOUND.
• 0.2.2 is a patch release focused on real-world AssetMapper vendor layouts. No migration is expected, but clean generated test artifacts if you were affected by prior symlink behavior.

Implementation Patterns

• Prefer the loader variant for packages with chunk files, subpath imports, or non-trivial vendor layouts. Use the symlink variant for simpler packages where a direct filesystem link is enough.
• Add regression coverage for the vendor shapes that commonly break: directory packages with stimulus.index.js + stimulus.index-<hash>.js, packages that expose both CSS and JS entries, and packages with subpath imports such as jquery-ui/ui/widgets/sortable.
• Keep the test importmap focused on JavaScript entries. type: 'css' entries are skipped in 0.2.2, but leaving CSS out of the test-facing importmap makes failures easier to reason about.
• In CI, run the AssetMapper install/compile step before the Node tests, then run the bundle’s test command. Treat ERR_MODULE_NOT_FOUND as a regression signal for vendor entry resolution.
• When a package exposes subpath modules, test those through the loader variant. The symlink variant intentionally skips subpath file entries, so it is not a reliable way to validate subpath specifiers.
• Inspect the generated node_modules/<pkg> shim when debugging. Check the generated entry file, package.json, and whether the package resolved to index.js vs the intended <basename>.index.js.

Gotchas and Tips

• If you see ERR_MODULE_NOT_FOUND for packages like @hotwired/stimulus, upgrade to 0.2.2 and clear generated node_modules artifacts before retesting.
• CSS importmap entries can be dangerous for Node tests because a generated node_modules/<pkg>/index.js can shadow the package’s real JS entry. 0.2.2 skips type: 'css' entries, but avoid relying on CSS entries in test importmaps.
• Never let the test tooling write through an existing symlink under node_modules/. Previous behavior could write index.js and package.json into assets/vendor/; if that happened, remove the contaminated generated files from source assets.
• Subpath file entries are skipped in the symlink variant. This is intentional; use the loader variant or import the package’s main entry when testing with symlinks.
• After upgrading, clean stale generated shims/symlinks. Existing bad artifacts can make a fixed release still look broken.
• Use the package’s documented variant configuration as the main extension point. Choose the variant deliberately per project/test suite rather than mixing symlink and loader assumptions in the same test setup.