Announcing elm-embed 0.1.0

[emmabastas]

Hello everyone, I’m exited to announce the very first version of elm-embed. This is intended as a rough sketch for an idea, a basis for discussion.

Would love if you wanted to try it out!

What is elm-embed?

elm-embed is a tool for parsing external data like environment variables and file content and then embedding it in Elm code.

You do this with embedders, which is any Elm declaration with the type Embed.Task living inside the special folder elm-embed-scripts. I can for example embed an environment variable pointing to the server my app should target, so that I can use my own local server for development. I would do that with an embedder like this:

-- elm-embed-scripts/Server.elm
serverUrl : Embed.Task String
serverUrl =
    Embed.Environment.string "target_server"

If I then run elm-embed run with the env variable target_server set to localhost:8080 I would get the resulting code in src/Generated/Server.elm which can then be imported in the rest of the codebase.

-- src/Generated/Server.elm
serverUrl : String
serverUrl =
    "localhost:8080"

External data can also be validated and transformed with Embed.andThen. So it is possible to do more advanced stuff, like parsing a markdown document with elm-markdown and reporting any errors at build-time.

Installation

Pre-built binary availible for Linux Here. Just unzip, give execute permissions and place on your path. Detailed instructions here.

Mac and Windows users will need to build from source for now, the process is the same as for the Elm compiler. If you’re on Mac or Windows and want to give elm-embed a try, send me a message and that would really motivate me to fix binaries.

Next steps

I would really love to hear what use cases you can see yourself having for elm-embed, that way I can make more informed design decisions. So please let me know in a comment here, somewhere in the Elm Slack, or this Github issue.

And at this point in the project, any kind of questions, thoughts or discussion relating to elm-embed is very welcome.

All the best to y’all

[terezka]

This is so cool! Can’t wait to try it out!

[georgesboris]

This looks really promising! And your timing – I promise I was going to try and build something like this today!

FYI – I’m running a Mac and my use case would be to read .md files (with frontmatter) and parse those into some Elm code I would use to create a client-side search engine. (contents of the website are small enough that I could do it without any server setup).

Wishlist: I would love to be able to specify the name of the target folder. As I’m also using elm-pages and elm-tailwind-modules and both their generated files live under /gen.

Thanks so much for working on this!

[emmabastas]

Thank you so much for the use case and wishlist. The most obvious way to support /gen would be to implement an output flag for the generated code. But I’d like to think about it a bit first, and see how other tools do it, some output in gen while others output in src.

And I’ll let you know when OSX binaries are available .

[neurodynamic]

This looks really cool; and very potentially useful for a project I’m working on right now. Another interested Mac user here!

[choonkeat]

Background: I’m currently using scripts like env2file.js which produces src/Env.elm like

module Env exposing (..)

{-| environment variable AWS_REGION
-}
awsRegion =
     "us-east-1" 

which I reference in elsewhere in my app as Env.awsRegion. with function-level dead code elimination I don’t have to worry about the unreferenced env values. Same strategy for file content and file paths as : String functions

Wondering what I’m missing by not approaching the problem like elm-embed?

[wolfadex]

I’ve used GitHub - jaredramirez/elm-constants: Generate constant values in Elm from your environment before and liked it, but once elm-embed has a Mac installer I’d probably start recommending it at work instead. The main advantage I see is being able to generate not only non-String values, but also being able to wrqp env tokens and ids in phantom types.

[emmabastas]

With regards to environment variables. With elm-embed you …

@wolfadex Summed it up nicely. But if you are satisfied with your current solution, then I don’t see a need to switch to elm-embed.

[choonkeat]

@wolfadex

The main advantage I see is being able to generate not only non-String values, but also being able to wrqp env tokens and ids in phantom types.

i think “i can transform those String to phantom types” but keep slipping my mind that it would be even better if those values don’t exist as String in my codebase at all thanks for the reminder