Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/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
elm elm-architecture elm-format learning learning-elm tutorial
Last synced: 5 days ago
JSON representation
:rainbow: discover the beautiful programming language that makes front-end web apps a joy to build and maintain!
- Host: GitHub
- URL: https://github.com/dwyl/learn-elm
- Owner: dwyl
- Created: 2016-11-05T09:45:12.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2022-01-14T12:25:34.000Z (almost 3 years ago)
- Last Synced: 2024-10-20T00:44:33.027Z (15 days ago)
- Topics: elm, elm-architecture, elm-format, learning, learning-elm, tutorial
- Language: HTML
- Homepage: https://github.com/dwyl/learn-elm
- Size: 730 KB
- Stars: 482
- Watchers: 156
- Forks: 41
- Open Issues: 97
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
Awesome Lists containing this project
- awesome-ccamel - dwyl/learn-elm - :rainbow: discover the beautiful programming language that makes front-end web apps a joy to build and maintain! (HTML)
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](https://youtu.be/R2FtMbb-nLs?t=47m36s)
(_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**_."
> If anything in `this` guide is unclear/unexplained,
_please_ help us _improve_ by opening an issue:
https://github.com/dwyl/learn-elm/issues [](https://github.com/dwyl/learn-elm/issues)
### 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**_](https://insights.stackoverflow.com/survey/2018/#technology-programming-scripting-and-markup-languages)
... so _**why**_ should we even _consider_ it?
There are _many_ "_technical_" reasons for using Elm:
+ "[_**Pure**_](https://drboolean.gitbooks.io/mostly-adequate-guide/content/ch3.html)"
_functional style_ means all your functions are _**predictable**_
and thus _**very reliable**_.
No surprises even when you are working with
a distributed team of dozens of people!
+ [***Immutable state***](https://softwareengineering.stackexchange.com/questions/235558/what-is-state-mutable-state-and-immutable-state) means there are _fewer_ (_often zero_)
["_**side effects**_"](https://softwareengineering.stackexchange.com/questions/40297/what-is-a-side-effect)
+ _**Fewer language features**_
[**_lowers_ cognitive load**](https://blog.prototypr.io/design-principles-for-reducing-cognitive-load-84e82ca61abd)
when you're reading (_other people's_) code
+ **_Much_ less to learn** than comparable "Stacks" e.g:
+ **React** + Redux + Flow + Immutable + Babel + all the other setup code...
+ **Angular 2** + Typescript + Babel + ReactiveX + etc.
(_bottom line is: elm is `less` to learn_!)
+ _**Much faster**_ than React.js or Angular 2 in _all_ ["***benchmarks***"](https://elm-lang.org/blog/blazing-fast-html-round-two)
+ **Built-in ["_Time Travelling_" Debugger](https://www.youtube.com/watch?v=DSjbTC-hvqQ&feature=youtu.be&list=PLglJM3BYAMPH2zuz1nbKHQyeawE4SN0Cd&t=1633)**
that lets you record and replay actions in a user session
(_thus **eliminating** the need for manually
writing Selenium/Nightwatch tests!_)
+ _**Helpful/friendly compiler `error` messages**_ that _inform you **exactly**_
what is wrong (_during compilation_) _before_ you attempt
to view your app in the browser/device.
+ Evan surveyed the _existing_ web programming languages for his
University thesis and Elm is the `result` of that study
(_borrows ideas from several places and assembles them
into a cohesive beautiful package much how Apple made the original iPhone..._)
The _reason(s)_ we [@**dwyl**](https://twitter.com/dwyl) are _using_
the `elm` _ecosystem_ is because it has:
+ _**beginner-friendly** and thriving **community** where everyone is welcome_
+ _clear **leadership** from nice + smart people and_
+ _excellent **documentation**
(which greatly reduces frustration for beginners)_
+ _a shared **mission** to build the **best**
graphical user interfaces for the web!_
These are a _few_ of [our **_favourite_ things**](https://youtu.be/0IagRZBvLtw).
## 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:
[](https://youtu.be/cgXhMc8M4X4)
https://youtu.be/cgXhMc8M4X4
### Isn't "Functional Programming" _Difficult_...?
If you **`feel`** like _**F**unctional **P**rogramming_
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:
[](
https://en.wikipedia.org/wiki/Phrases_from_The_Hitchhiker%27s_Guide_to_the_Galaxy#Don.27t_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](#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_"](https://youtu.be/GVJL9oXgsAA),
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
+ A **Computer** with:
+ **Node.js _Installed_** (_if you don't already have node get it here_: https://nodejs.org/en/download/ )
+ **Text Editor** (_any will do but we recommend_ https://atom.io/ _because it has good Elm syntax/plugins_)
+ Internet Access (_just so you can install elm and the modules_)
+ Some **JavaScript/Node.js Knowledge** (_ideally you have built a basic Node/JS app before,
but no "major" experience required/expected_)
### _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"](https://github.com/dwyl/learn-elm/issues/45).
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**](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:
```sh
git clone https://github.com/dwyl/learn-elm.git && cd learn-elm
```
#### 2. Install
Install the node.js dependencies (`elm` platform):
```sh
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}!
+ Open the `examples/hello-world.elm` file in your editor.
+ Move your cursor to the 3rd line and change `name` to your name!
#### 4. Server Time!
Run the `elm-reactor` command to start the _server:_
```sh
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**](https://github.com/rtfeldman)
(_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:
```js
npm install elm -g
```
> avoid using [`sudo`](https://stackoverflow.com/questions/16151018/npm-throws-error-without-sudo)
as you _really_ should be following the
[principle of least privilege](https://en.wikipedia.org/wiki/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`.
```js
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:
```elm
describe "Dummy test"
[ test "dummy test description" <|
\() ->
Expect.equal actualValue expectedValue
]
```
For example:
``` elm
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](https://medium.com/@_rchaves_/testing-in-elm-93ad05ee1832#.3i3ibxcxz)
and
[elm community](https://package.elm-lang.org/packages/elm-community/elm-test/2.1.0).
## 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](https://github.com/dwyl/learn-circleci).
### 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](https://github.com/dwyl/learn-elm/tree/master/examples/elm-flags).
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
+ Great collection of examples and posts:
https://github.com/isRuslan/awesome-elm
### Selected Articles (_Our Favourites_)
+ How to use Elm at work: https://elm-lang.org/blog/how-to-use-elm-at-work
(_or work for DWYL where you're actively encouraged to use it!_)
+ JavaScript interoperability: https://guide.elm-lang.org/interop/
+ How to add Elm to _existing_ JS codebase: https://tech.noredink.com/post/126978281075/walkthrough-introducing-elm-to-a-js-web-app
+ How Elm made our work better (_success story_):
https://futurice.com/blog/elm-in-the-real-world
### General Functional Programming (background reading)
+ Objects Should Be Immutable: https://www.yegor256.com/2014/06/09/objects-should-be-immutable.html
### Further reading
+ Once you've gotten to grips with making Single Page Apps with Elm,
adding routing in can really improve your user's experience!
If they're seeing a different `view`,
it can make sense for the URL to change as well,
so that the user can navigate back to the same view as they please.
+ Check [this article from staticapps.org](https://staticapps.org/articles/routing-urls-in-static-apps/)
out for a little more info on routing in Single Page Apps in General
+ And get started [by going to the routing section of the elm-tutorial gitbook](https://sporto.gitbooks.io/elm-tutorial/content/en/07-routing/02-routing.html)
to learn how to implement it in your Elm app!
+ [This example](https://github.com/elm-lang/navigation/tree/master/examples)
from the _elm-lang/navigation_ github repo is super helpful too.
## Videos
+ Mutable vs Immutable: https://youtu.be/5qQQ3yzbKp8
+ Learning Functional Programming with JavaScript (Anjana Vakil): https://youtu.be/e-5obm1G_FY
+ Functional Programming from First Principles (Erik Meijer):
https://youtu.be/a-RAltgH8tw
+ Teaching functional programming to noobs (Rob Martin):
https://youtu.be/bmFKEewRRQg
+ Functional Programming is Terrible (Rúnar Bjarnason):
https://youtu.be/hzf3hTUKk8U
### Promising but _incomplete_:
+ Learn You an `Elm` https://learnyouanelm.github.io/
(_lots of "Todo" items and last updated about a year go_)
[](http://hits.dwyl.com/dwyl/learn-elm)