search

dwyl / learn-elm

:rainbow: discover the beautiful programming language that makes front-end web apps a joy to build and maintain!
https://github.com/dwyl/learn-elm
483 stars 43 forks source link
elm elm-architecture elm-format learning learning-elm tutorial

readme

learn elm

Why?

It's difficult to introduce elm to someone who has never heard of it before without sounding "evangelical" ...
We've tried our best to be "objective" and factual; the fact is that Elm is awesome.
Which is why so many JS projects have "borrowed" (shamelessly copied) it's ideas. (Redux, Immutable.js, etc.)

@rtfeldman put it best in his 6 Months of Elm in Production talk (which we highly recommend watching!)
"If you take two products and compare them on feature-checklists that gets you
a very inaccurate picture of what it's going to be like to actually use them."

6-months-of-elm-comparison

If anything in this guide is unclear/unexplained, please help us improve by opening an issue: https://github.com/dwyl/learn-elm/issues contributions welcome

Why Not Just use XYZ JavaScript Framework (which has similar features) ?

Most of us are already comfortable with JavaScript and it is still (and will remain) the most popular programming language ... so why should we even consider it?

There are many "technical" reasons for using Elm:

The reason(s) we @dwyl are using the elm ecosystem is because it has:

These are a few of our favourite things.

What?

Elm is a programming language for creating web browser-based graphical user interfaces. Elm is purely functional, and is developed with emphasis on usability, performance, and robustness. It advertises "no runtime exceptions in practice," made possible by the Elm compiler's static type checking.

It's difficult to overstate how game-changing elm, the elm-architecture and elm-platform are to web development right now! The fact that Dan Abramov was "inspired" by Elm (architecture and debugger) for Redux and React Hot-Reloader respectively, should tell you that there's "something" here worth exploring ...

Great Video Intro to Elm (by Jessica Kerr)

We highly recommend watching Jessica Kerr's "Adventures in Elm" from GOTO Conference 2016: image

https://youtu.be/cgXhMc8M4X4

Isn't "Functional Programming" Difficult...?

If you feel like Functional Programming is "complicated" you aren't alone, it's a perfectly normal sentiment:

I tried functional programming in JavaScript before, it was confusing...

All we can say to that is:

dont-panic

Fear not, we have witnessed many non-mathematician people (without a Computer Science or "Engineering" background) learning Elm "from scratch" and while some initially felt that Functional Programming was a steep learning curve, because it's quite different from what we were used to (procedural/imperative/mutable...).

We found that the Elm language is actually really small and focussed
and when we break it down there are only a handful of concepts
we need to understand before we can start reading/writing code.

Tip: if you want to understand the core concepts, jump to the Language section below.

Who?

If you haven't felt the pain of trying to debug/maintain/extend code you did not originally write, or have not worked on a sufficiently large app to feel the "fix one thing breaks two other features" "whack-a-mole", you might not not see the benefit of the elm ecosystem ...

But we urge you to consider the list in the "Why?" section (above) and if any of those points appeals to you,
give elm 5 minutes of your time today to try the "Quick-Start" below!

How?

The best place to start is with the "Official Guide". But we have condensed their "Install" guide into the 5-minute instructions below:

Pre-requisites

Recommended Pre-Elm Learning: Elm Architecture

While it's not a "Pre-requisite", we (highly) recommend learning/understanding The Elm Architecture ("TEA") before learning Elm (the language) to flatten the "Elm learning curve". To that end, we wrote an introductory step-by-step tutorial for the Elm Architecture in JavaScript: https://github.com/dwyl/learn-elm-architecture-in-javascript

Quick-Start (5 Mins)

Enough talk, let's see an example!

1. Clone this repository

On your local machine, open a terminal window and run the following command:

git clone https://github.com/dwyl/learn-elm.git && cd learn-elm

2. Install

Install the node.js dependencies (elm platform):

npm install

Note: We install elm (the elm compiler) locally for the "quick-start". If you decide to use it for your own project(s), you can install it globally using npm install -g elm

3. Hello {Name}!

4. Server Time!

Run the elm-reactor command to start the server:

node_modules/.bin/elm-reactor

Elm-reactor has now started the server on your localhost.

Note if you install elm globally you will be able to type elm-reactor without the node_modules/.bin/ (relative path)

If you're curious why you're running a server to view the output of your elm code, it's because elm is compiled to JavaScript, and it's fiddly to have to compile your code manually every time you want to see the output. With elm reactor this is handled for you. Read more about it here: https://elmprogramming.com/elm-reactor.html

5. View in Browser

View the entire repository in your web browser by going to: http://localhost:8000/

Click on example/hello-world.elm to see your Hello World! This shows how it would compile into HTML without having to use elm-make (which we'll save for later)!

6. Reflect

You just saw how easy it is to get started with elm, how do you feel? Was it "difficult"? Better or worse than your experience of learning any other technical concept/tool/language?

Please share your thoughts!


In-depth Step-by-Step Tutorial (60mins)

The best place to start your elm journey is with the (free) "Official Guide" https://guide.elm-lang.org/

At the time of writing, the entire "Official" guide to Elm (GitBook) (written Evan Czaplicki, creator of Elm, and improved by the community) is 136 pages (with generous spacing in the code examples). The guide is readable/learnable in less than a day including trying all the example and demo code. If you prefer to download and read the guide "offline" (e.g: on public transport during your commute to work...), You can download a PDF, ePub or Mobi (Kindle) for free at: https://www.gitbook.com/book/evancz/an-introduction-to-elm/details

Frontend Masters Workshop

It's not often we find a half-decent tutorial on a subject we are trying to learn. We were delighted to discover that Richard Feldman (one of the core contributors to elm) has produced a workshop (videos + learning materials) for learning elm: https://frontendmasters.com/workshops/elm/ + https://github.com/rtfeldman/elm-workshop

While it costs $39 we think it's an absolute bargain!

Note if you have a lack of funds to pay for a subscription to get access to the workshop, contact us! (we can help!)

Installation

The official installation instructions for Mac, Linux & Windows: https://guide.elm-lang.org/install.html

Install the Elm Platform Globally on your Computer

Yes, install it globally so you get the elm command which has a several useful functions. Including elm reactor a hot-reloading webserver that allows you write/test simple apps fast. and elm make which compiles your App.

Install using NPM with the following command:

npm install elm -g

avoid using sudo as you really should be following the principle of least privilege.

Remember, if you are adding Elm to a project which will be deployed on a hosting service (such as heroku) you will need to add elm to the dependencies in your package.json.

npm install elm --save

Install Elm Format

There are many things to love about elm but something you can appreciate right away is elm-format. It's a tool that formats your elm code so that it is consistent with the community standard format.

Installation instructions

  1. Download the current version of elm-format found at: https://github.com/avh4/elm-format
  2. Unzip the downloaded file and move the elm-format executable to a location in your PATH variable. If the unzipped file is in your Downloads folder, you could move it with the following terminal command: mv ~/Downloads/elm-format /usr/local/bin/elm-format, which will move it to the default path.
  3. Install the elm-format package in your text editor. In Atom, type apm install elm-format into the terminal, or install via Packages (filter by elm)
  4. Set elm-format to format your work on save. In Atom, Open Settings CMD + , (Linux: ctrl + ,), click Packages, filter by 'elm', then click on the elm-format package's settings button. Set the elm-format command path setting and ensure the 'format on save' checkbox is selected.

For more advice on elm development environment setup: https://github.com/knowthen/elm/blob/master/DEVSETUP.md

Language

Help Wanted summarizing the language features! for now see: https://elm-lang.org/docs/syntax

Testing

Ready to start testing? Simply follow these 3 steps:

1) npm i -g elm-test

2) elm test init This will set up your test environment and give you 7 dummy tests in your newly created test folder

3) Run elm test or the very nice elm test --watch which will re-run your tests as you write them

The general format of the tests are:

describe "Dummy test"
    [ test "dummy test description" <|
      \() ->
        Expect.equal actualValue expectedValue
    ]

For example:

all : Test
all =
  describe "My first test"
      [ test "Addition test works correctly" <|
        \() ->
            Expect.equal (2 + 2) 4
      , test "Our subtraction function works correctly" <|
        \() ->
          -- here we are pretending we have a subtract function that takes 2 arguments
            Expect.equal (subtract 10 5) 5
      ]

More info on testing can be found at testing in elm and elm community.

Continuous Integration

Circle CI

To set up your elm project on Circle CI, copy over our circle.yml and circle-dependencies.sh and follow the instructions on our Circle CI tutorial.

Travis CI

See: https://github.com/dwyl/learn-travis#elm-lang-project

Flags

Flags allow you to pass data from Javascript to Elm as part of the initial state of your application.

See our working flags example. Here we pass the URL from Javascript to Elm (via the script tags in our index.html).

Run npm install,elm install and npm start to see the output.

Further/Background Reading

Selected Articles (Our Favourites)

General Functional Programming (background reading)

Further reading

Videos

Promising but incomplete:

HitCount