[AssetMapper] Adding infos to be forwarded to package maintainers in case of error

[ThomasLandauer]

Page: https://symfony.com/doc/6.4/frontend/asset_mapper.html#importing-3rd-party-javascript-packages

Closes #19558

Thanks to @tofsjonas for figuring this out at tofsjonas/sortable#68

You might say it's not the job of the Symfony docs to tell JavaScript package maintainers how to set up their packages.

But: With so many packages out there, I doubt that importing them will always work. So instead of leaving Symfony users back frustrated, I think it's better to tell them what they can do. And that it's not AssetMapper's fault that it didn't work out.

[smnandre]

This cut the example in two. Could you group your two additions in a dedicated paragraph ?

And a 404 could have many other reasons, i fear this could be misdirecting :|

[smnandre]

This should be in the "handling 3rd party" section, as this paragraph states "if a packages includes a CSS files".

[ThomasLandauer]

Yeah, you're right, there is no good place for this currently. So I'd like to reorganize the sections and merge "Importing 3rd Party JavaScript Packages" with "Handling 3rd-Party CSS" and move them downwards, under the CSS section.

Reasons:

• 3rd party JavaScript comes too early, IMO. How the importmap works at all should be explained first.
• Same for CSS: People need to understand how their own CSS works first, before caring about 3rd party CSS.
• Many external packages contain CSS, so it's better to deal with these two topics (3rd party JS and 3rd party CSS) in one section. Then the content of this PR would fit there nicely.

What do you think?

[smnandre]

As i see it, required JS packages is the main reason to use importmaps.

CSS files is just a bonus, for those who want to install them.

[javiereguiluz]

I like this proposal. Two quick comments:

(1) This:

include `"main":` and `"module":` to the package's `package.json`

maybe can be reworded as follows to make it more clear:

include the `main` and `module` options to the package's `package.json`

(2) Do we have a reference for the package.json format? Ideally I'd like to add a link so people can read more about these new options that they need to add.

Thanks.

[ThomasLandauer]

@javiereguiluz OK, but where to put it? What do you think about merging the two sections (see above)?

@smnandre No matter what people are using it for: I think handling local files should be explained first, to make people understand the basics.

[smnandre]

I'm just stating a fact: AssetMapper may be for local CSS files first..

But ImportMap is a tool made for 3rd party scripts / dependencies first.

[javiereguiluz]

Thanks Thomas! This is now merged. I reworded and changed the location a bit as mentioned in the discussion. See 64eb515