JS/Web interop follow up

[MaryaBelanger]

A few things to improve the recently added JS interop docs based on feedback

1) Conceptual overview of the two new layers

Request: from @mit-mit

...more high-level conceptual information on the Overview page, especially around explaining each of the two new layers (package:web and dart:js_interop) in an overview fashion

Where: https://dart.dev/interop/js-interop

2) Getting started walkthrough / tutorial

Request: #5674

...More beginner friendly step by step examples

Where: https://dart.dev/interop/js-interop/tutorials (getting-started)

Notes:

• NOT migration-centric, but starting from scratch.
  • Getting more asks for just getting started with JS interop vs just migration help (3)
• Replace the current/old web getting started page
  • Start by just translating to package:web
  • Highlight important package:web stuff
    • Might require the doc to be significantly expanded on, not just updated.
  • Include how to run and debug with webdev, connect with devtools
• Next (another doc, probably), "now we have this js library that we want to use in our web app..."
  • Use new JS interop to incopoprate JS APIs
  • How to use JS types, or external APIs that use JS types
• Call out differences between JS and Wasm throughout the doc for certain things like casting and stuff
  • Incorporate numbers somehow, show how Wasm and JS use numbers differently
• Note at the end "try this out with experimental Wasm"
  • (will have to do their own hookups)

Related:

• Rewrite dart:html library page for package:web #5525

3) Expanded migration guidance

Request: dart-lang/sdk#55352

...concrete side by side examples of old vs new

Where: https://dart.dev/interop/js-interop/tutorials (migration)

Notes:

For existing Dart package maintainers, expanding on examples and references is more useful than tutorial-style content.

• Walkthrough of a package migration
  • "Migrating to Wasm" angle (which is just js interop and package:web migration)
• Cover holistic pov: tooling, workflow changes, tests, "everything"
• Focus on 1:1 migration code examples for specific changes in JS types, areas most problematic for users
• Crafted examples with numbers changes, other semantics differences sprinkled in (Lean heavily on existing jsinterop docs for reference)
  • Target more common use cases (rather than trying to base it on a real example).
• Nice to have: a list of real migration examples, with different types of migrations/migrations that cover different things

[projektorius96]

It's really nice to see the iceberg has finally moved. Way to go ♥

As a JavaScript to Dart developer I'd love to see more beginner friendly examples, especially the ones oriented towards HTML Canvas API using package:web/web.dart, actually I have just tried to ask Gemini for help making a starter template (entry-point) that I subsequently have tried to compile using dart compile js <entry-point>, yet the compiling stage itself has failed, perhaps due to inconsistencies provided for my metaphorical <entry-point> by the Gemini AI : the AI is aware of newest Dart VM as well as dart:js_interop, so keeping in mind I could not glue up things with a AI help, the docs is the only source-of-true to make it happen otherwise. Looking forward to see some updates, hopefully soon !

[bivens-dev]

This may not be the right place too but wanted to call out I found it very difficult how to handle working with things like WebWorkers in the new package and pass messages back and forth.

[MaryaBelanger]

This is the right place to call out things you'd like to see documented, or things you wish had been documented (even if you've already moved on or figured it out). Thank you both @bivens-dev and @projektorius96!

[projektorius96]

Just to recap, I guess when it comes about HTML specification and beyond most of developers peoples , layman like me, would love to see more of easy-to-grasp "from scratch" examples for the following:

• A boilerplate for Web Component, how to set up, register and instantiate;
• A boilerplate for HTML Canvas or SVG, again how to set up, register and instantiate for each specification respectively;

To follow up, more beginner friendly boilerplates working with Web APIs, just to name a few IndexedDB for in-browser state management, simple Web Workers setup as per @bivens-dev remark or even communication examples, as per issue etc.

Cheers !

P.S. Sorry for repeating myself again and again, just cannot wait for changes coming, really excited and appreciate the feedback Dart communitive give us ! To name a few @MaryaBelanger, @parlough

[projektorius96]

Hi, just curious, what's the current status of dart:js_interop ? Is it work in progress at all ? I've just stumbled upon @mit-mit blog post on Medium for Dart 3.4 that also mentions improvements made on the dart:js_interop, perhaps source code itself, and not the docs.

Cheers !

[MaryaBelanger]

Hey @projektorius96! The changes referenced in the blog post are all listed in the changelog here. They're mostly incremental improvements for known issues, so nothing big to cover, just that we're making it a little better all the time!

[projektorius96]

Hey @projektorius96! The changes referenced in the blog post are all listed in the changelog here. They're mostly incremental improvements for known issues, so nothing big to cover, just that we're making it a little better all the time!

What are about the docs themselves, anything to share even though some work-in-progress tutorial ? Nearly two months passed since the request, I mean guys at least some beginner tutorial to catch the drift, I am not requesting a complete codelab. Afterall you got complete Flutter team, why when those guys do not do some Work in Progress timeline with incremental tutorials, similarly to how Manning reveals their work in progress.

It seems that in this world easier to do things by yourself, then wait for breadcrumbs. Really sad, yet not the first time Google lets people down.

[MaryaBelanger]

@projektorius96 Ah I see, yes we have started work on addressing 2) described above, so a getting started tutorial on using JS interop in a new project/from scratch.

[projektorius96]

@projektorius96 Ah I see, yes we have started work on addressing 2) described above, so a getting started tutorial on using JS interop in a new project/from scratch.

Is any of the documentation planed to be published with Dart 3.5 ? Roughly another two months passed since last enquiry, just wanted to double check, see if any heads up could be given towards the process ?

Cheers !