Skip to content

Developer experience: Not always clear how to init from JS #122

Open
@cmditch

Description

@cmditch

I appreciate how much effort and focus the Elm community devotes to clear & thorough documentation. In an effort to continue improving the docs, I'll go over an experience I recently had trying to use Browser.sandbox for a SSCCE.

I found that it was not very clear from the Browser.element or Browser.sandbox docs how to initialize them within JS.

I spent quite a bit of time pouring over the package docs, elm guide, and elm guide examples to no avail.

I eventually happened upon https://guide.elm-lang.org/interop/ , which shows the use of the node field, but it's not clear when this field is relevant wrt sandbox, element, document, application. I also found https://guide.elm-lang.org/webapps/, but this only shows how to init a document.

Potential ways to ameliorate this confusion:

  1. Include js snipptes in the Browser docs.
  2. Include js/html snippets in the guides examples instead of only pure Elm.
  3. Include something like the table below as a quick and clear reference in the Browser docs and Elm guide (with help from @Janiczek).
+----------------------+-------------------+------------------------+
| entry point js param | uses `node` field | supports `flags` field |
+----------------------+-------------------+------------------------+
| Platform.worker      | no                | yes                    |
+----------------------+-------------------+------------------------+
| Browser.sandbox      | yes               | no                     |
+----------------------+-------------------+------------------------+
| Browser.element      | yes               | yes                    |
+----------------------+-------------------+------------------------+
| Browser.document     | no                | yes                    |
+----------------------+-------------------+------------------------+
| Browser.application  | no                | yes                    |
+----------------------+-------------------+------------------------+
  1. All of the above
  2. None of the above and something better?

Thanks!
Coury

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions