In reading the recent conversations about ports, I’ve noticed a few patterns that I’ve been thinking about
for the past few days. I’ve also been doing a fair amount of work with ports lately. As a result,
I have a few ideas I’d like to share about how I think we can work together as a community to
improve folks’ experiences with ports.
These are the patterns I’ve noticed:
Lots of people seem come away frustrated when trying to use ports
A few people have had pretty positive experiences using ports (I’m in this category)
I see lots of conversations about ports in a general sense
I see few conversations about trying to solve specific problems using ports
My hypothesis is that devs working with ports mostly follow this pattern:
Developer has a problem with no native Elm solution
Developer works independently to solve the problem with ports
Developer is successful and quietly happy
or
Developer fails and becomes frustrated with ports
Developer vents about ports online
Developer tries to find a port escape hatch
Developer becomes frustrated with Elm
I think it would be nicer if something like this was more common:
Developer has a problem with no native Elm solution
Developer checks a well known resource for port implementations
Developer finds a reference implementation or a similar problem and is happy
or
There is no reference implementation so Developer posts on discourse to share their problem
The community helps create a pure Elm solution
or
The community helps design a nice port API
To help with move us a bit closer toward the second process, I’ve created an elm-port-examples repo. Right now it just has a localStorage implementation that I’m quite happy with, but I hope to add a websocket example in the next month or so. I
put advice for getting help from the community in the README, as well as a list of folks willing to help out
with new port problems (just me so far!).
If this is something you’re interested in helping out with, there are a few things you can do.
Use the examples from the repo and provide feedback
Start new threads about specific issues you’re facing with ports
If you have a nice port solution for something, contribute it to the repo
If you’ve had a good experience with ports and feel comfortable helping others, open a PR to add your name to the list of people willing to help in the repo
Hi @matt.cheely,
perhaps following examples can be for someone helpful. It was my first touch with Elm and now these codes are outdated.
elm-port - just generating numbers and their displaying in graphs (used plotly library), see demo
elm-forecast - a very small SPA for showing forecast of weather (with small help from @s-m-i-t-a), used elm-mdl and plotly lib for both graphs, see demo
Do you imagine the elm-port-examples repository being analogous to Arch Linux’s AUR? I.e, packages that are not part of the Elm ecosystem per se, and which are not supported by the Elm language developers directly, but which the community finds helpful in certain circumstances. I think this would be a great addition to the community.
Personally I think that would be dangerous, as it could lead to a large number of projects building upon/depending upon those packages, thus creating inertia against change when Elm-native solutions become available.
I do think @matt.cheely’s repository and volunteer list is a great idea, but I feel it should contain a small selection of easy to understand, well documented and curated examples of graded complexity to teach beginner’s how to use ports. I don’t think it should become a library of off-the-shelf production-ready solutions as that could hurt Elm in the long term: there’s a reason port based packages are not allowed in the official package repository…
@Jess_Bromley, I appreciate the inherent tension between best practices and convenience. If we accept the Arch Linux : AUR :: Elm : elm-port-examples analogy, then we should examine whether the presence of AUR packages has retarded adoption of Arch or made it less safe to use. I would argue that it has not.
While a repository of ports-based solutions might lead to heavy adoption of packages that do not have official support, but this is not any different than the current situation. Devs who code their own ports are “on their own” with respect to official Elm support.
Such a repository is likely to increase adoption of Elm overall. Once a project is built upon Elm, one would expect that maintenance of said project would attempt to follow best practices, including transitioning to officially supported solutions when available. The onus would be on the community to make clear that these ports solutions would not have official support and to point to native solutions where available.
In essence this approach places the responsibility for best practices on the individual developer and the community rather than on the language designers.
I said this in the other thread, but the only way to actually ease this pain is to have tooling to help users structure this problem in a sane and conventional way across the community. Think about which scenario is harder and more painful… migrating from one local storage package that everyone has installed, or migrating from 1000 variations people have written off the cuff in every app?
I will throw up a PR with some examples when I get some free time, excited to see if this can become a useful resource.
Hey this is a great idea. It would be great to have a central place to point to when people are asking about these things.
Can I offer to volunteer to make something? Maybe:
I once had to implement a facebook login button into an Elm project. It involved some fairly complex actor-model logic between the button and the app, but in the end it worked out well.
We have Joakin’s Elm-Canvas package, which is awesome. But in order to upgrade a project of mine to Elm 0.19, I need something to find a way to do canvas drawing stuff through ports. I have an idea in my head on how to do it, just need to experiment with it. I would be happy to write up an example and donate it, but maybe since this is still in the proof of concept stage for me its not ready to be an example?
A media player, a play list of music, and buttons you can click that play, pause, or move to next.
Some kind of complicated scrolling functionality, maybe like a long list with a nav bar that lets you automatically scroll to certain items or categories. I have had to do complicated scroll stuff twice for work
I see a lot of folks asking what my long-term vision for the project is and speculating about what kind of approach would be best for Elm, so it seems worth commenting a little on that point. If you have a strong opinion on this front, brace yourself for disappointment.
I don’t actually think the project needs a particular long-term vision right now. It’s okay for projects to start small and evolve organically. Mostly I just think the community needs a central hub to talk about and work on ports where we can solve problems together. There are a lot of ways I can imagine this turning out, and I’m not confident in making predictions about any of them. Any of these seem feasible to me:
We could throw up a couple of browser APIs and library examples and that might be enough examples for folks to work from and the pressure around ports just sort of dies off
We might discover a huge corpus of 3rd party client libraries that are essential to people’s business relationships, but for which there are no underlying API docs to build native Elm solutions from, and thus are quite valuable as ports
The project might end up being a hub for people who show up looking for ports to bind to things, but discover other people with the same problem who then collaborate on pure Elm solutions.
???
Profit
Sorry, I lost the plot a little at the end of that list. My point is that it’s fine to just work on things for now without trying to plot out an optimum path to success.
If you look through the README on the project, I do have some ideas about how things should be prioritized, but that’s not a long-term plan, just something to help figure out what to focus on.
In the absence of specific needs, I think the best things to focus on are interactions with native browser APIs, since ports are the only option folks have for those. That would suggest #2 and #3 as likely options. It seems like @Dan_Abrams is well on his way with the media player already. It sounds like you have a specific need for the canvas interactions, so I’d suggest that one. Of course, it’s your time so feel free to spend it however works best for you!
I made my canvas ports implementation, and it seems to work well. I’ll look over the code later, and if I am still happy with it I’ll make a PR to your repo @matt.cheely
I just did an integration with Plaid Link over ports, and would be happy to share that experience. I looked for inspiration in libraries like stripe but had to do more data exchange, so went my own way.
I’d also love to see ways of using ports to make development more enjoyable, like how I wrote a simple port for better JSON debugging.
Thanks for putting time and energy into improving ports! At this point I think they are the cleanest interface I’ve seen from one language/runtime to another, and I really appreciate that.
@jc00ke - I’d definitely be curious to know more about your Plaid Link integration. One thing I’m hoping to learn more about from this project is how people weigh the trade-offs around integrating with an organization’s public JS library via ports vs creating an Elm package that interfaces directly with the API.
Developer finds a reference implementation or a similar problem and is happy
I’d rather generalize this to ‘finds advice on how to proceed’, which may include not only an example usage of ports, but also perhaps e.g. web components, or the suggestion that Elm isn’t actually the right tool for the job in the first place.
Do you know of a good example Elm package that interfaces directly with a library’s API? In my case, there are no real docs on the libraries API (it’s a lot like Stripe Checkout, where you only get a few callbacks to hook into.)
I don’t know of any specific examples of elm libraries for a particular organization’s API, but I am keeping an eye out. It’s not something that has come up for me directly. If you hear of any good examples, let me know!
If you want to share an example of when you want ports, or a time when you are personally confused about how to solve the problem with ports, we can do things there.
