More beginner-friendly examples for a new JS interop, not just breadcrumbs and inconsistent boilerplates, please ! [FEATURE REQUEST]

[projektorius96]

Coming from JavaScript world, the docs for JS Interop, in my sheer opinion are useless, we need more beginner friendly step by step basis examples ! Take as an example usage section, the usage section focuses on Dart, but does not even show a pseudo idiomatic code which explain how it binds the stuff with JavaScript, at least syntax-wise.

I'd love to see the approach where everything about JS interop is explained step by step basis. I am currently actively building HTML Canvas based PWA similar to online Desmos but offline-first, and because the codebase grows exponentially I decided to ship to Dart rather to controversial TypeScript. Yes, my goal is to bind it with Dart, so package:web would do a job, but dart:js_interop examples around which package:web is built, like I said before, bunch of inconsistent boilerplates that cannot be easily grasped, to be honest a guy who can write Golang code, I could understand the C interop better than all is written in the JS Interop section on Dart docs. I don't know about other people experience towards this question, but that's me. The only I have recently read on Discord channel, that the guy chosen TypeScript over Dart, because of lack of documentation. Keeping in mind all happens under Google, it's really sad, just like Steve Ballmer said "Developers Developers Developers", I say "Documentation Documentation Documentation" ! Hopefully the administrators will take this features request positively, cheers !

[parlough]

Thanks for the issue and feedback!

I definitely agree that we need more step-by-step documentation here (for JS and other forms of interop). This form of JS interop was just released this past month and was a large migration from previous styles, so the initial documentation focused on migrating from the old system. I hope we can find time soon to introduce more documentation, including tutorial like docs, but we are also happy to accept pull requests in the mean time!

Is there a specific topic or example that you think would be helpful to your learning experience? Any insight here would help guide development of future learning materials.

If you notice other specific issues or areas of improvement, please file more issues at https://github.com/dart-lang/site-www/issues.

If you have questions using JS interop, consider asking on the Dart Discord and if you find any issues or notice any developer experience issues, open an issue on the Dart SDK repository.

Thanks again and I'm sorry the new JS-interop documentation didn't have what you were looking for yet.

[srawlins]

@parlough should I transfer this to https://github.com/dart-lang/site-www/issues?

[parlough]

If you are able to, yes please :)

[srawlins]

Oh I forgot, there's... red tape or something. I cannot. :(

I figured it out. Transferred.

[jarrodcolburn]

Since the dart:js_interop library says "WARNING: This library is still a work in progress" I kinda expect the team to be more focused on developing the features, than documenting them. So although, I agree it's lacking, I kinda think it's expected atm.

That said, (maybe I'm missing it) but the thing I would appreciate seeing that I don't currently, and would be a step in this what I believe OP thinks is the right direction is...

How to use/load .js files to use the dart bindings?

And, What should the project directory/file structure look like?

Take for instance the Example on Usage page for Top-level Interop members Which provides a js and dart snippet.

globalThis.name = 'global';
globalThis.isNameEmpty = function() {
  return globalThis.name.length == 0;
}

@JS()
external String get name;

@JS()
external set name(String value);

@JS()
external bool isNameEmpty();

Unfortunately, the js and dart above it doesn't really tell you how to load the js. Like is the js supposed to be in a .js file? If so where?

I know from trying it in a Simple Dart Web app that we can save the js to something like myscript.js and edit the index.html to include...

<script src="myscript.js" >

...to load it. But I don't really see that documented, and I'm not even sure if editing the html is the recommended way of loading js. I actually hope not.

I see importModule() method exists, but I don't see an usage or example on how to use it. Is that what I should be using? If so, what's the setup for the modules, and where do they belong in the project?