mithril

<head> <meta charset=UTF-8> <title> Installation - Mithril.js</title> <link href="https://fonts.googleapis.com/css?family=Open+Sans" rel=stylesheet> <link href=style.css rel=stylesheet> <link rel=icon type=image/png sizes=32x32 href=favicon.png> <meta name=viewport content="width=device-width,initial-scale=1"> </head> <body> <header> <section> <a class=hamburger href=javascript:;>≡</a> <h1><img src=logo.svg> Mithril <small>2.0.3</small></h1> <nav> <a href=index.html>Guide</a> <a href=api.html>API</a> <a href=https://gitter.im/MithrilJS/mithril.js>Chat</a> <a href=https://github.com/MithrilJS/mithril.js>GitHub</a> </nav> </section> </header> <main> <section> <h1 id=installation><a href=#installation>Installation</a></h1> <ul> <li>Getting Started<ul> <li><a href=index.html>Introduction</a></li> <li><strong><a href=installation.html>Installation</a></strong><ul> <li><a href=#cdn>CDN</a></li> <li><a href=#npm>npm</a></li> <li><a href=#quick-start-with-webpack>Quick start with Webpack</a></li> <li><a href=#typescript>TypeScript</a></li> </ul> </li> <li><a href=simple-application.html>Tutorial</a></li> <li><a href=learning-mithril.html>Learning Resources</a></li> <li><a href=support.html>Getting Help</a></li> </ul> </li> <li>Resources<ul> <li><a href=jsx.html>JSX</a></li> <li><a href=es6.html>ES6+ on legacy browsers</a></li> <li><a href=animation.html>Animation</a></li> <li><a href=testing.html>Testing</a></li> <li><a href=examples.html>Examples</a></li> <li><a href=integrating-libs.html>3rd Party Integration</a></li> <li><a href=paths.html>Path Handling</a></li> </ul> </li> <li>Key concepts<ul> <li><a href=vnodes.html>Vnodes</a></li> <li><a href=components.html>Components</a></li> <li><a href=lifecycle-methods.html>Lifecycle methods</a></li> <li><a href=keys.html>Keys</a></li> <li><a href=autoredraw.html>Autoredraw system</a></li> </ul> </li> <li>Social<ul> <li><a href=https://github.com/MithrilJS/mithril.js/wiki/JOBS>Mithril Jobs</a></li> <li><a href=contributing.html>How to contribute</a></li> <li><a href=credits.html>Credits</a></li> <li><a href=code-of-conduct.html>Code of Conduct</a></li> </ul> </li> <li>Misc<ul> <li><a href=framework-comparison.html>Framework comparison</a></li> <li><a href=change-log.html>Change log/Migration</a></li> <li><a href=https://mithril.js.org/archive/v1.1.6/ >v1 Documentation</a></li> <li><a href=https://mithril.js.org/archive/v0.2.5/ >v0.2 Documentation</a></li> </ul> </li> </ul> <h3 id=cdn><a href=#cdn>CDN</a></h3> <p>If you're new to JavaScript or just want a very simple setup to get your feet wet, you can get Mithril from a <a href=https://en.wikipedia.org/wiki/Content_delivery_network>CDN</a>:</p> <pre><code class=language-html><script src="https://unpkg.com/mithril/mithril.js"></script></code></pre> <hr> <h3 id=npm><a href=#npm>npm</a></h3> <pre><code class=language-bash>$ npm install mithril --save</code></pre> <p>TypeScript type definitions are available from DefinitelyTyped. They can be installed with:</p> <pre><code class=language-bash>$ npm install @types/mithril --save-dev</code></pre> <p>For example usage, to file issues or to discuss TypeScript related topics visit: <a href=https://github.com/MithrilJS/mithril.d.ts>https://github.com/MithrilJS/mithril.d.ts</a></p> <p>Type definitions for pre-release versions of Mithril (on the <code>next</code> branch) align with the <code>next</code> branch of the <a href=https://github.com/MithrilJS/mithril.d.ts/tree/next>types development repo</a>. You can install these types with:</p> <pre><code class=language-bash>$ npm install -D MithrilJS/mithril.d.ts#next</code></pre> <hr> <h3 id=quick-start-with-webpack><a href=#quick-start-with-webpack>Quick start with Webpack</a></h3> <ol> <li><p>Initialize the directory as an npm package</p> <pre><code class=language-bash>$ npm init --yes</code></pre> </li> <li><p>install required tools</p> <pre><code class=language-bash>$ npm install mithril --save $ npm install webpack webpack-cli --save-dev</code></pre> </li> <li><p>Add a "start" entry to the scripts section in <code>package.json</code>.</p> <pre><code class=language-javascript>{ // ... "scripts": { "start": "webpack src/index.js --output bin/app.js -d --watch" } }</code></pre> </li> <li><p>Create <code>src/index.js</code> file.</p> <pre><code class=language-javascript>import m from "mithril"; m.render(document.body, "hello world");</code></pre> </li> <li><p>create <code>index.html</code></p> <pre><code class=language-html><!DOCTYPE html> <body> <script src="bin/app.js"></script> </body></code></pre> </li> <li><p>run bundler</p> <pre><code class=language-bash>$ npm start</code></pre> </li> <li><p>open <code>index.html</code> in a browser</p> </li> </ol> <h4 id=step-by-step><a href=#step-by-step>Step by step</a></h4> <p>For production-level projects, the recommended way of installing Mithril is to use npm.</p> <p>npm is the default package manager that is bundled w/ Node.js. It is widely used as the package manager for both client-side and server-side libraries in the JavaScript ecosystem. Download and install <a href=https://nodejs.org>Node</a>; npm is bundled with that and installed alongside it.</p> <p>To use Mithril via npm, go to your project folder, and run <code>npm init --yes</code> from the command line. This will create a file called <code>package.json</code>.</p> <pre><code class=language-bash>npm init --yes # creates a file called package.json</code></pre> <p>Then, to install Mithril, run:</p> <pre><code class=language-bash>npm install mithril --save</code></pre> <p>This will create a folder called <code>node_modules</code>, and a <code>mithril</code> folder inside of it. It will also add an entry under <code>dependencies</code> in the <code>package.json</code> file</p> <p>You are now ready to start using Mithril. The recommended way to structure code is to modularize it via CommonJS modules:</p> <pre><code class=language-javascript>// index.js var m = require("mithril") m.render(document.body, "hello world")</code></pre> <p>Modularization is the practice of separating the code into files. Doing so makes it easier to find code, understand what code relies on what code, and test.</p> <p>CommonJS is a de-facto standard for modularizing JavaScript code, and it's used by Node.js, as well as tools like <a href=http://browserify.org/ >Browserify</a> and <a href=https://webpack.js.org/ >Webpack</a>. It's a robust, battle-tested precursor to ES6 modules. Although the syntax for ES6 modules is specified in Ecmascript 6, the actual module loading mechanism is not. If you wish to use ES6 modules despite the non-standardized status of module loading, you can use tools like <a href=https://rollupjs.org/ >Rollup</a> or <a href=https://babeljs.io/ >Babel</a>.</p> <p>Most browser today do not natively support modularization systems (CommonJS or ES6), so modularized code must be bundled into a single JavaScript file before running in a client-side application.</p> <p>A popular way for creating a bundle is to setup an npm script for <a href=https://webpack.js.org/ >Webpack</a>. To install Webpack, run this from the command line:</p> <pre><code class=language-bash>npm install webpack webpack-cli --save-dev</code></pre> <p>Open the <code>package.json</code> that you created earlier, and add an entry to the <code>scripts</code> section:</p> <pre><code class=language-json>{ "name": "my-project", "scripts": { "start": "webpack src/index.js --output bin/app.js -d --watch" } }</code></pre> <p>Remember this is a JSON file, so object key names such as <code>"scripts"</code> and <code>"start"</code> must be inside of double quotes.</p> <p>The <code>-d</code> flag tells webpack to use development mode, which produces source maps for a better debugging experience.</p> <p>The <code>--watch</code> flag tells webpack to watch the file system and automatically recreate <code>app.js</code> if file changes are detected.</p> <p>Now you can run the script via <code>npm start</code> in your command line window. This looks up the <code>webpack</code> command in the npm path, reads <code>index.js</code> and creates a file called <code>app.js</code> which includes both Mithril and the <code>hello world</code> code above. If you want to run the <code>webpack</code> command directly from the command line, you need to either add <code>node_modules/.bin</code> to your PATH, or install webpack globally via <code>npm install webpack -g</code>. It's, however, recommended that you always install webpack locally and use npm scripts, to ensure builds are reproducible in different computers.</p> <pre><code>npm start</code></pre><p>Now that you have created a bundle, you can then reference the <code>bin/app.js</code> file from an HTML file:</p> <pre><code class=language-html><html> <head> <title>Hello world</title> </head> <body> <script src="bin/app.js"></script> </body> </html></code></pre> <p>As you've seen above, importing a module in CommonJS is done via the <code>require</code> function. You can reference npm modules by their library names (e.g. <code>require("mithril")</code> or <code>require("jquery")</code>), and you can reference your own modules via relative paths minus the file extension (e.g. if you have a file called <code>mycomponent.js</code> in the same folder as the file you're importing to, you can import it by calling <code>require("./mycomponent")</code>).</p> <p>To export a module, assign what you want to export to the special <code>module.exports</code> object:</p> <pre><code class=language-javascript>// mycomponent.js module.exports = { view: function() {return "hello from a module"} }</code></pre> <p>In the <code>index.js</code>, you would then write this code to import that module:</p> <pre><code class=language-javascript>// index.js var m = require("mithril") var MyComponent = require("./mycomponent") m.mount(document.body, MyComponent)</code></pre> <p>Note that in this example, we're using <code>m.mount</code>, which wires up the component to Mithril's autoredraw system. In most applications, you will want to use <code>m.mount</code> (or <code>m.route</code> if your application has multiple screens) instead of <code>m.render</code> to take advantage of the autoredraw system, rather than re-rendering manually every time a change occurs.</p> <h4 id=production-build><a href=#production-build>Production build</a></h4> <p>If you open bin/app.js, you'll notice that the Webpack bundle is not minified, so this file is not ideal for a live application. To generate a minified file, open <code>package.json</code> and add a new npm script:</p> <pre><code class=language-json>{ "name": "my-project", "scripts": { "start": "webpack src/index.js --output bin/app.js -d --watch", "build": "webpack src/index.js --output bin/app.js -p", } }</code></pre> <p>You can use hooks in your production environment to run the production build script automatically. Here's an example for <a href=https://www.heroku.com/ >Heroku</a>:</p> <pre><code class=language-json>{ "name": "my-project", "scripts": { "start": "webpack -d --watch", "build": "webpack -p", "heroku-postbuild": "webpack -p" } }</code></pre> <hr> <h3 id=alternate-ways-to-use-mithril><a href=#alternate-ways-to-use-mithril>Alternate ways to use Mithril</a></h3> <h4 id=live-reload-development-environment><a href=#live-reload-development-environment>Live reload development environment</a></h4> <p>Live reload is a feature where code changes automatically trigger the page to reload. <a href=https://github.com/mattdesl/budo>Budo</a> is one tool that enables live reloading.</p> <pre><code class=language-bash># 1) install npm install mithril --save npm install budo -g # 2) add this line into the scripts section in package.json # "scripts": { # "start": "budo --live --open index.js" # } # 3) create an `index.js` file # 4) run budo npm start</code></pre> <p>The source file <code>index.js</code> will be compiled (bundled) and a browser window opens showing the result. Any changes in the source files will instantly get recompiled and the browser will refresh reflecting the changes.</p> <h4 id=vanilla><a href=#vanilla>Vanilla</a></h4> <p>If you don't have the ability to run a bundler script due to company security policies, there's an options to not use a module system at all:</p> <pre><code class=language-html><html> <head> <title>Hello world</title> </head> <body> <script src="https://unpkg.com/mithril/mithril.js"></script> <script src="index.js"></script> </body> </html></code></pre> <pre><code class=language-javascript>// index.js // if a CommonJS environment is not detected, Mithril will be created in the global scope m.render(document.body, "hello world")</code></pre> <hr> <small>License: MIT. © Leo Horie.</small> </section> </main> <script src=https://cdnjs.cloudflare.com/ajax/libs/prism/1.6.0/prism.min.js defer></script> <script src=https://cdnjs.cloudflare.com/ajax/libs/prism/1.6.0/components/prism-jsx.min.js defer></script> <script src=https://unpkg.com/mithril@2.0.3/mithril.js async></script> <script> document.querySelector(".hamburger").onclick = function() { document.body.className = document.body.className === "navigating" ? "" : "navigating" document.querySelector("h1 + ul").onclick = function() { document.body.className = '' } } </script>