Skip to content

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

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

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

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