{"id":13394079,"url":"https://github.com/dwyl/learn-elm","last_synced_at":"2025-05-15T09:05:56.994Z","repository":{"id":40605278,"uuid":"72917308","full_name":"dwyl/learn-elm","owner":"dwyl","description":":rainbow: discover the beautiful programming language that makes front-end web apps a joy to build and maintain!","archived":false,"fork":false,"pushed_at":"2025-01-06T10:35:00.000Z","size":763,"stargazers_count":487,"open_issues_count":97,"forks_count":43,"subscribers_count":155,"default_branch":"master","last_synced_at":"2025-05-10T01:51:23.265Z","etag":null,"topics":["elm","elm-architecture","elm-format","learning","learning-elm","tutorial"],"latest_commit_sha":null,"homepage":"https://github.com/dwyl/learn-elm","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dwyl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-11-05T09:45:12.000Z","updated_at":"2025-03-23T11:29:33.000Z","dependencies_parsed_at":"2025-01-17T23:01:22.264Z","dependency_job_id":"d94fe68e-f86c-4331-a843-c2e6c5b7afa5","html_url":"https://github.com/dwyl/learn-elm","commit_stats":{"total_commits":145,"total_committers":22,"mean_commits":6.590909090909091,"dds":"0.37241379310344824","last_synced_commit":"2b7b2a0f98d87e6951132812eb1814edff9ced45"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dwyl%2Flearn-elm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dwyl%2Flearn-elm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dwyl%2Flearn-elm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dwyl%2Flearn-elm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dwyl","download_url":"https://codeload.github.com/dwyl/learn-elm/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254198426,"owners_count":22030967,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["elm","elm-architecture","elm-format","learning","learning-elm","tutorial"],"created_at":"2024-07-30T17:01:08.260Z","updated_at":"2025-05-15T09:05:56.917Z","avatar_url":"https://github.com/dwyl.png","language":"HTML","readme":"# learn `elm`\n\n## Why?\n\n\u003e It's _difficult_ to _introduce_ elm to someone\nwho has _never_ heard of it before without sounding \"_evangelical_\" ... \u003cbr /\u003e\nWe've tried our best to be \"_objective_\" and ***factual***;\nthe _fact_ is that Elm is ***awesome***. \u003cbr /\u003e\nWhich is why _so many_ JS projects\nhave \"borrowed\" (_shamelessly copied_) it's ideas. (Redux, Immutable.js, etc.)\n\u003cbr /\u003e\n\n\u003e @rtfeldman put it best in his\n[**6 Months of Elm in Production** talk](https://youtu.be/R2FtMbb-nLs?t=47m36s)\n(_which we **highly recommend** watching!_)\u003cbr /\u003e\n\"_If you take **two products** and **compare** them\non **feature-checklists**\nthat gets you \u003cbr /\u003e\na **very inaccurate picture**\nof what it's going to be like to actually **use them**_.\"\n\n![6-months-of-elm-comparison](https://cloud.githubusercontent.com/assets/194400/20147838/be5d2746-a6a1-11e6-91af-5149c5bf345b.jpg)\n\n\u003e If anything in `this` guide is unclear/unexplained,\n_please_ help us _improve_ by opening an issue:\nhttps://github.com/dwyl/learn-elm/issues [![contributions welcome](https://img.shields.io/badge/contributions-welcome!-brightgreen.svg?style=flat)](https://github.com/dwyl/learn-elm/issues)\n\n### Why _Not_ Just use XYZ JavaScript Framework (_which has similar features_) ?\n\n_Most_ of us are _already comfortable_ with `JavaScript`\nand it is _still_ (_and will remain_) the\n[_**most popular programming language**_](https://insights.stackoverflow.com/survey/2018/#technology-programming-scripting-and-markup-languages)\n... so _**why**_ should we even _consider_ it?\n\nThere are _many_ \"_technical_\" reasons for using Elm:\n\n+ \"[_**Pure**_](https://drboolean.gitbooks.io/mostly-adequate-guide/content/ch3.html)\"\n_functional style_ means all your functions are _**predictable**_\nand thus _**very reliable**_. \u003cbr /\u003e\nNo surprises even when you are working with\na distributed team of dozens of people!\n+ [***Immutable state***](https://softwareengineering.stackexchange.com/questions/235558/what-is-state-mutable-state-and-immutable-state) means there are _fewer_ (_often zero_)\n[\"_**side effects**_\"](https://softwareengineering.stackexchange.com/questions/40297/what-is-a-side-effect)\n+ _**Fewer language features**_\n[**_lowers_ cognitive load**](https://blog.prototypr.io/design-principles-for-reducing-cognitive-load-84e82ca61abd)\nwhen you're reading (_other people's_) code\n+ **_Much_ less to learn** than comparable \"Stacks\" e.g:\n  + **React** + Redux + Flow + Immutable + Babel + all the other setup code...\n  + **Angular 2** + Typescript + Babel + ReactiveX + etc.\n  (_bottom line is: elm is `less` to learn_!)\n+ _**Much faster**_ than React.js or Angular 2 in _all_ [\"***benchmarks***\"](https://elm-lang.org/blog/blazing-fast-html-round-two)\n+ **Built-in [\"_Time Travelling_\" Debugger](https://www.youtube.com/watch?v=DSjbTC-hvqQ\u0026feature=youtu.be\u0026list=PLglJM3BYAMPH2zuz1nbKHQyeawE4SN0Cd\u0026t=1633)**\n that lets you record and replay actions in a user session\n (_thus **eliminating** the need for manually\n   writing Selenium/Nightwatch tests!_)\n+ _**Helpful/friendly compiler `error` messages**_ that _inform you **exactly**_\nwhat is wrong (_during compilation_) _before_ you attempt\nto view your app in the browser/device.\n+ Evan surveyed the _existing_ web programming languages for his\nUniversity thesis and Elm is the `result` of that study\n(_borrows ideas from several places and assembles them\n  into a cohesive beautiful package much how Apple made the original iPhone..._)\n\nThe _reason(s)_ we [@**dwyl**](https://twitter.com/dwyl) are _using_\nthe `elm` _ecosystem_ is because it has:\n+ _**beginner-friendly** and thriving **community** where everyone is welcome_\n+ _clear **leadership** from nice + smart people and_\n+ _excellent **documentation**\n(which greatly reduces frustration for beginners)_\n+ _a shared **mission** to build the **best**\ngraphical user interfaces for the web!_\n\nThese are a _few_ of [our **_favourite_ things**](https://youtu.be/0IagRZBvLtw).\n\n\n## What?\n\n### `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.\n\n\u003e It's _difficult_ to _overstate_ how _game-changing_ `elm`,\nthe `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\nrespectively, should tell you that there's \"_something_\" here worth exploring ...\n\n### Great Video Intro to Elm (_by Jessica Kerr_)\n\nWe _highly_ recommend watching Jessica Kerr's\n\"***Adventures in Elm***\" from GOTO Conference 2016:\n[![image](https://cloud.githubusercontent.com/assets/194400/22403008/7a878200-e602-11e6-9239-e292fa97c6e1.png)](https://youtu.be/cgXhMc8M4X4)\n\nhttps://youtu.be/cgXhMc8M4X4\n\n### Isn't \"Functional Programming\" _Difficult_...?\n\nIf you **`feel`** like _**F**unctional **P**rogramming_\nis \"_complicated_\" you aren't _alone_,\nit's a _perfectly normal_ sentiment:\n\n\u003e I _tried_ functional programming in JavaScript before, it was _confusing_...\n\nAll we can say to that is:\n\n[![dont-panic](https://cloud.githubusercontent.com/assets/194400/20135968/74ed05d6-a66a-11e6-9f30-f50f911053e6.png)](\n  https://en.wikipedia.org/wiki/Phrases_from_The_Hitchhiker%27s_Guide_to_the_Galaxy#Don.27t_Panic)\n\nFear not, we have witnessed _many_ non-mathematician people\n(_without a Computer Science\nor \"Engineering\" background_) learning Elm \"from scratch\"\nand while some _initially_ **`felt`** that Functional Programming\nwas a _steep_ learning curve,\n_because_ it's _quite_ different from what we were _used_ to\n(_procedural/imperative/mutable_...).\n\nWe **`found`** that the Elm language is actually really _small and focussed_\u003cbr /\u003e\nand when we break it down there are only a handful of concepts \u003cbr /\u003e\nwe need to _understand_ before we can start reading/writing code.\n\n\u003e **Tip**: if you want to _understand_ the core concepts,\njump to the [Language](#language) section below.\n\n## Who?\n\nIf you haven't felt the _pain_ of trying to debug/maintain/extend\ncode you did not _originally write_, or have not worked\non a sufficiently large app to `feel` the\n\"_fix one thing breaks two other features_\" [\"_whack-a-mole_\"](https://youtu.be/GVJL9oXgsAA),\nyou _might not_ not see the _benefit_ of the `elm` ecosystem ...\n\nBut we _urge_ you to consider the list in the \"Why?\" section (_above_)\nand if _any_ of those points appeals to you, \u003cbr /\u003e\ngive elm ***5 minutes*** of your\ntime _**today**_ to _try_ the \"_**Quick-Start**\" below_!\n\n\n## How?\n\nThe best place to start is with the \"_Official Guide_\". But we have _condensed_ their \"Install\" guide into the **5-minute** instructions below:\n\n### Pre-requisites\n\n+ A **Computer** with:\n  + **Node.js _Installed_** (_if you don't already have node get it here_: https://nodejs.org/en/download/ )\n  + **Text Editor** (_any will do but we recommend_ https://atom.io/ _because it has good Elm syntax/plugins_)\n+ Internet Access (_just so you can install elm and the modules_)\n+ Some **JavaScript/Node.js Knowledge** (_ideally you have built a basic Node/JS app before,\nbut no \"major\" experience required/expected_)\n\n### _Recommended_ Pre-Elm Learning: Elm Architecture\n\nWhile it's not a \"Pre-requisite\",\nwe (_highly_) _recommend_ learning/understanding\n**The Elm _Architecture_** (\"TEA\")\n`before` learning Elm (_the **language**_)\nto _flatten_ the\n[\"Elm learning curve\"](https://github.com/dwyl/learn-elm/issues/45).\nTo that end, we wrote an _introductory **step-by-step**_\ntutorial for the Elm Architecture in JavaScript:\n[https://github.com/dwyl/**learn-elm-architecture**-in-**javascript**](https://github.com/dwyl/learn-elm-architecture-in-javascript)\n\n### Quick-Start (_5 Mins_)\n\nEnough talk, let's see an _example_!\n\n#### 1. Clone this repository\n\nOn your local machine, open a terminal window and run the following command:\n\n```sh\ngit clone https://github.com/dwyl/learn-elm.git \u0026\u0026 cd learn-elm\n```\n\n#### 2. Install\n\nInstall the node.js dependencies (`elm` platform):\n\n```sh\nnpm install\n```\n\u003e **Note**: We install `elm` (_the `elm` compiler_)\n_locally_ for the \"_quick-start_\".\nIf you decide to use it for your own project(s),\nyou _can_ install it _globally_ using\n`npm install -g elm`\n\n#### 3. Hello {Name}!\n\n+ Open the `examples/hello-world.elm` file in your editor.\n+ Move your cursor to the 3\u003csup\u003erd\u003c/sup\u003e line and change `name` to your name!\n\n#### 4. Server Time!\n\nRun the `elm-reactor` command to start the _server:_\n\n```sh\nnode_modules/.bin/elm-reactor\n```\n\nElm-reactor has now started the server on your localhost.\n\n\u003e Note if you install elm _globally_ you will be able to type `elm-reactor`\nwithout the `node_modules/.bin/` (_relative path_)\n\n\u003e If you're curious why you're running a server to view the output\nof your ```elm``` code, it's because ```elm``` is compiled to JavaScript,\nand it's fiddly to have to compile your code manually\nevery time you want to see the output. With ```elm reactor```\nthis is handled for you. Read more about it here:\nhttps://elmprogramming.com/elm-reactor.html\n\n\n#### 5. View in Browser\n\nView the entire repository in your web browser by going to:\nhttp://localhost:8000/\n\nClick on _example/hello-world.elm_ to see your Hello World!\nThis shows how it\nwould compile into `HTML` _without_ having to use `elm-make`\n(which we'll save for later)!\n\n\n#### 6. _Reflect_\n\nYou just saw how _easy_ it is to get started with `elm`,\nhow do you _feel_?\nWas it \"_difficult_\"?\nBetter or _worse_ than your experience of learning\nany other technical concept/tool/language?\n\nPlease share your thoughts!\n\n\u003cbr /\u003e\n\n\n### In-depth Step-by-Step Tutorial (_60mins_)\n\nThe _best_ place to start your elm journey\nis with the (_free_) \"_Official Guide_\"\nhttps://guide.elm-lang.org/ \u003cbr /\u003e\n\n\u003e At the time of writing, the _entire_ \"_Official_\" guide to Elm (GitBook)\n(_written Evan Czaplicki, creator of Elm, and improved by the community_)\nis ***136 pages*** (_with generous spacing in the code examples_).\n\u003e The guide is readable/learnable in _less than a day_\nincluding trying all the example and demo code.\n\u003e If you prefer to download and read the guide \"offline\"\n(_e.g: on public transport during your commute to work..._),\nYou can download a PDF, ePub or Mobi (Kindle) for _free_ at:\nhttps://www.gitbook.com/book/evancz/an-introduction-to-elm/details\n\n### Frontend Masters Workshop\n\nIt's _not often_ we find a _half-decent_ tutorial\non a subject we are trying to learn.\nWe were _delighted_ to discover that\n[**Richard Feldman**](https://github.com/rtfeldman)\n(_one of the `core` contributors to `elm`_)\nhas produced a workshop (_videos + learning materials_)\nfor learning `elm`: https://frontendmasters.com/workshops/elm/ + https://github.com/rtfeldman/elm-workshop\n\nWhile it costs **$39** we think it's an _absolute bargain_!\n\n\u003e **Note** if you have a lack of funds to pay for a _subscription_\nto get access to the workshop, contact us! (_we can help!_)\n\n\u003c!--\n\u003e `@TODO`: write _comprehensive_ notes on the content in the workshop!\n--\u003e\n\n## Installation\n\nThe _official_ installation instructions for Mac, Linux \u0026 Windows:\nhttps://guide.elm-lang.org/install.html\n\n### Install the Elm Platform _Globally_ on your Computer\n\nYes, install it _globally_ so you get the `elm` command which\nhas a several useful functions. Including `elm reactor`\na hot-reloading webserver that allows you write/test simple apps fast.\nand `elm make` which compiles your App.\n\nInstall using NPM with the following command:\n\n```js\nnpm install elm -g\n```\n\n\u003e avoid using [`sudo`](https://stackoverflow.com/questions/16151018/npm-throws-error-without-sudo)\nas you _really_ should be following the\n[principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege).\n\nRemember, if you are adding Elm to a project\nwhich will be deployed on a hosting service (such as heroku)\nyou will need to add elm to the dependencies in your `package.json`.\n\n```js\nnpm install elm --save\n```\n\n### Install Elm Format\n\nThere are many things to love about ```elm```\nbut something you can appreciate right away is `elm-format`.\nIt's a tool that formats your ```elm``` code\nso that it is consistent\nwith the community standard format.\n\n**Installation instructions**\n1. Download the current version of elm-format found\nat: https://github.com/avh4/elm-format\n2. Unzip the downloaded file and move the elm-format executable\nto a location in your PATH variable.\nIf the unzipped file is in your Downloads folder,\nyou could move it with the following terminal\ncommand: `mv ~/Downloads/elm-format /usr/local/bin/elm-format`,\nwhich will move it to the default path.\n3. Install the elm-format package in your text editor.\nIn Atom, type `apm install elm-format` into the terminal,\nor install via Packages (filter by `elm`)\n4. Set elm-format to format your work on save.\nIn Atom, Open Settings `CMD + ,` (Linux: `ctrl + ,`),\nclick Packages, filter by 'elm',\nthen click on the elm-format package's settings button.\nSet the `elm-format` command path setting\nand ensure the 'format on save' checkbox is selected.\n\nFor more advice on `elm` development environment setup: https://github.com/knowthen/elm/blob/master/DEVSETUP.md\n\n### Language\n\n\u003e Help Wanted summarizing the language features!\n\u003e for now see: https://elm-lang.org/docs/syntax\n\n## Testing\n\nReady to start testing?\nSimply follow these 3 steps:\n\n1) ``` npm i -g elm-test```\n\n2) ``` elm test init ```\n  This will set up your test environment and give you 7\n  dummy tests in your newly created test folder\n\n3) Run ```elm test``` or the **very nice** ```elm test --watch```\nwhich will re-run your tests as you write them\n\nThe general format of the tests are:\n```elm\ndescribe \"Dummy test\"\n    [ test \"dummy test description\" \u003c|\n      \\() -\u003e\n        Expect.equal actualValue expectedValue\n    ]\n```\nFor example:\n``` elm\nall : Test\nall =\n  describe \"My first test\"\n      [ test \"Addition test works correctly\" \u003c|\n        \\() -\u003e\n            Expect.equal (2 + 2) 4\n      , test \"Our subtraction function works correctly\" \u003c|\n        \\() -\u003e\n          -- here we are pretending we have a subtract function that takes 2 arguments\n            Expect.equal (subtract 10 5) 5\n      ]\n```\n\nMore info on testing can be found at\n[testing in elm](https://medium.com/@_rchaves_/testing-in-elm-93ad05ee1832#.3i3ibxcxz)\nand\n[elm community](https://package.elm-lang.org/packages/elm-community/elm-test/2.1.0).\n\n## Continuous Integration\n\n### Circle CI\n\nTo 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).\n\n### Travis CI\n\nSee: https://github.com/dwyl/learn-travis#elm-lang-project\n\n## Flags\n\nFlags allow you to pass data from Javascript to Elm\nas part of the initial state of your application.\n\nSee our [working flags example](https://github.com/dwyl/learn-elm/tree/master/examples/elm-flags).\nHere we pass the URL from Javascript to Elm\n(via the script tags in our `index.html`).\n\nRun ```npm install```,```elm install``` and ```npm start```\nto see the output.\n\n## Further/Background Reading\n\n+ Great collection of examples and posts:\nhttps://github.com/isRuslan/awesome-elm\n\n### Selected Articles (_Our Favourites_)\n\n+ How to use Elm at work: https://elm-lang.org/blog/how-to-use-elm-at-work\n(_or work for DWYL where you're actively encouraged to use it!_)\n+ JavaScript interoperability: https://guide.elm-lang.org/interop/\n+ How to add Elm to _existing_ JS codebase: https://tech.noredink.com/post/126978281075/walkthrough-introducing-elm-to-a-js-web-app\n+ How Elm made our work better (_success story_):\nhttps://futurice.com/blog/elm-in-the-real-world\n\n### General Functional Programming (background reading)\n\n+ Objects Should Be Immutable: https://www.yegor256.com/2014/06/09/objects-should-be-immutable.html\n\n### Further reading\n\n+ Once you've gotten to grips with making Single Page Apps with Elm,\nadding routing in can really improve your user's experience!\nIf they're seeing a different `view`,\nit can make sense for the URL to change as well,\nso that the user can navigate back to the same view as they please.\n  + Check [this article from staticapps.org](https://staticapps.org/articles/routing-urls-in-static-apps/)\n  out for a little more info on routing in Single Page Apps in General\n  + 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)\n  to learn how to implement it in your Elm app!\n  +  [This example](https://github.com/elm-lang/navigation/tree/master/examples)\n  from the _elm-lang/navigation_ github repo is super helpful too.\n\n## Videos\n\n+ Mutable vs Immutable: https://youtu.be/5qQQ3yzbKp8\n+ Learning Functional Programming with JavaScript (Anjana Vakil): https://youtu.be/e-5obm1G_FY\n+ Functional Programming from First Principles (Erik Meijer):\n  https://youtu.be/a-RAltgH8tw\n+ Teaching functional programming to noobs (Rob Martin):\n  https://youtu.be/bmFKEewRRQg\n+ Functional Programming is Terrible (Rúnar Bjarnason):\n  https://youtu.be/hzf3hTUKk8U\n\n### Promising but _incomplete_:\n\n+ Learn You an `Elm` https://learnyouanelm.github.io/\n(_lots of \"Todo\" items and last updated about a year go_)\n\n[![HitCount](https://hits.dwyl.com/dwyl/learn-elm.svg)](http://hits.dwyl.com/dwyl/learn-elm)\n","funding_links":[],"categories":["HTML","Learning Guides"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdwyl%2Flearn-elm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdwyl%2Flearn-elm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdwyl%2Flearn-elm/lists"}