[Documentation] Integration with Stimulus missing

[Nek-]

Hello,

I'm a big fan of TypeScript, so when I saw I could use this bundle, I tried it! (thanks for the good job so far)

I had no specific issue. But I feel like far too much is missing in the documentation and I found nothing anywhere to fix my issues. So I stopped using it instantly... But I decided to make an issue to help anyone that can to improve things!

1. There's no guide to switch from the default configuration of Symfony to a TypeScript approach. Therefore translating the existing code may be complicated
2. There's no guide on how to include new Types, and since Stimulus and Stimulus-Bundle types are not included, it does not work by default - with no info about it (I may have done something wrong, but I have no idea, I rely on PHPStorm red flags everywhere!)
3. An example of controller using TypeScript would be nice as well, and at least a link to this documentation: https://stimulus.hotwired.dev/reference/using-typescript
4. The suggested configuration (subfolder named typescript) does not work well with the default Symfony configuration, specifying that no configuration is required by default and it will look for the assets folder would be nice I think.

With the hope I help!

[maelanleborgne]

Hi and thanks for opening this issue.
I don't understand some of your points though, and I have the feeling that there might be a misunderstanding on what this bundle does : It is not a way to integrate with stimulus or live components. All it does is help you build your TypeScript files and expose the generated files through AssetMapper. Right now I don't intend to change the scope of the bundle, but I get that some people might want to use TypeScript with Stimulus.
If you feel like documenting your process of converting your Stimulus controllers to TypeScript, I'd be glad to add this as a new section in the documentation. I'm sure there is plenty of things that would be valuable to include in the documentation, and PR are very much appreciated :)

[tacman]

Indeed, this would be welcomed, in fact that's the exact reason I'm looking at this bundle.

On a related note, I only run asset-map:compile on deployment, on the production server. Reading the documentation, I'm not sure if I need to install this bundle in production (so the typescript files compile) or if I can run it in dev and check in the compiled js, and then continue to run the :compile command on production, without needing typescript.

[pavel-kolar]

Although this bundle works very well (it compiles all source typescript files, including external dependencies allowing them to be loaded via AssetMapper), it lacks support in IDEs (like PHPStorm). There is no way how to load .d.ts files to give IDE some grounds for typehinting and autocompletion features.

I think this issue is tightly bound to AssetMapper itself as it does not allow to require .d.ts files.

After some digging, I found out that AssetMapper combined with TypeScript is not yet ready for everything (https://symfonycasts.com/screencast/asset-mapper/setup). So when you do need the full TypeScript support, it is recommended to go back to "traditional" build-system approach (like Node.js and Webpack).

[maelanleborgne]

Hi, thank you for taking time to express the need.

About you IDE integration troubles, do you have typescript running locally on your machine ?

As of your last point, you're very right about this. Assetmapper's main purpose is to serve js module right away, which is somehow a very different approach from the what's done by build-based systems.

This bundle is mostly useful for people who would like to migrate from a Webpack to AssetMapper, or for people who use legacy TS code, or who simply like writing typescript and don't mind having to wait for the build to get their errors.

I'm not sure it's a reliable solution for full-featured TS codebase because it is not aligned with the AssetMapper philosophy, but sill we can try to improve as much as possible to make it pleasant to use.

Right now I don't have any project running with stimulus+assetmapper+typescript_bundle, if you have a demo project to provide I'd be happy to give a try at enhancing the integration with phpstorm.