Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update installation docs to use templates + esbuild instructions #2827

Closed
wants to merge 9 commits into from
Closed

Update installation docs to use templates + esbuild instructions #2827

Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
726d3bf
Bump minimatch from 3.0.4 to 3.1.2
dependabot[bot] Feb 7, 2023
a1159b7
Bump async from 2.6.3 to 2.6.4
dependabot[bot] Feb 7, 2023
88da9e5
hyperscript: handles shared empty attrs, fixes #2821
kfule Feb 15, 2023
ad9aa97
Fix typos in `stream()` docs (#2825)
mtsknn Mar 12, 2023
06a9cdc
update installation docs to use templates + esbuild
kevinfiol Apr 6, 2023
e51feac
fix errors and indentation
Sep 23, 2024
0d5db2a
Merge branch 'next' into kf/refactor-installation-page
Sep 23, 2024
0180ac4
undo changes to lockfile
Sep 23, 2024
0a61782
use consistent capitalization and naming
Sep 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
257 changes: 52 additions & 205 deletions docs/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,14 +16,14 @@ If you're new to JavaScript or just want a very simple setup to get your feet we
<script src="https://unpkg.com/mithril/mithril.js"></script>
```

If you would like to try out mithril without setting up a local environment, you can easily use an online playground at [flems.io/mithril](https://flems.io/mithril).
If you would like to try out Mithril.js without setting up a local environment, you can easily use an online playground at [flems.io/mithril](https://flems.io/mithril).

---

### npm

```bash
$ npm install mithril --save
$ npm install mithril
```

TypeScript type definitions are available from DefinitelyTyped. They can be installed with:
Expand All @@ -42,233 +42,80 @@ $ npm install -D MithrilJS/mithril.d.ts#next

---

### Quick start with Webpack
### Create a project locally

1. Initialize the directory as an npm package
```bash
$ npm init --yes
```
You can use one of several existing Mithril.js starter templates such as
* [mithril-vite-starter](https://github.com/ArthurClemens/mithril-vite-starter)
* [mithril-esbuild-starter](https://github.com/kevinfiol/mithril-esbuild-starter)
* [mithril-rollup-starter](https://github.com/kevinfiol/mithril-rollup-starter)

2. install required tools
For example, if you'd like to get started with `mithril-esbuild-starter`, run the following commands:
```bash
$ npm install mithril --save
$ npm install webpack webpack-cli --save-dev
```

3. Add a "start" entry to the scripts section in `package.json`.
```json
{
"...": "...",
"scripts": {
"start": "webpack ./src/index.js --output-path ./bin --watch"
}
}
```

4. Create `src/index.js` file.
```javascript
import m from "mithril";
m.render(document.body, "hello world");
```

5. create `index.html`
```html
<!DOCTYPE html>
<body>
<script src="bin/main.js"></script>
</body>
```

6. run bundler
```bash
$ npm start
```

7. open `index.html` in a browser
# Clone the the template to a directory of your choice
npx degit kevinfiol/mithril-esbuild-starter hello-world

Optionally, you can include Mithril.js as a global variable using Webpack's provide plugin, to avoid including `import m from "mithril"` across a large number of files:
```js
plugins: [
new webpack.ProvidePlugin({m: "mithril"}),
// ...
]
```
Then, you could remove the import line from step 4 (don't forget to restart Webpack if you ran it with `--watch`), and it will work just the same.

#### Step by step

For production-level projects, the recommended way of installing Mithril.js is to use npm.
# Navigate to newly scaffolded project
cd ./hello-world/

npm is the default package manager that is bundled with 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 [Node](https://nodejs.org); npm is bundled with that and installed alongside it.
# Install dependencies
npm install

To use Mithril.js via npm, go to your project folder, and run `npm init --yes` from the command line. This will create a file called `package.json`.

```bash
npm init --yes
# creates a file called package.json
# Build the app and watch for changes
npm run dev
Copy link
Contributor

@tbreuss tbreuss May 21, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems like port 8080 is the default. Maybe a hint could be helpful how to solve this, if port 8080 is already in use (in my case traefik).

port-8080-already-in-use

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I updated the port used by the esbuild template, and the dev script should log the port to the console by default.

```

Then, to install Mithril.js, run:
### Quick start with [esbuild](https://esbuild.github.io/)

1. Initialize the directory as an npm package.
```bash
npm install mithril --save
```

This will create a folder called `node_modules`, and a `mithril` folder inside of it. It will also add an entry under `dependencies` in the `package.json` file

You are now ready to start using Mithril. The recommended way to structure code is to modularize it via CommonJS modules:

```javascript
// index.js
var m = require("mithril")

m.render(document.body, "hello world")
$ npm init --yes
```

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.

CommonJS is a de-facto standard for modularizing JavaScript code, and it's used by Node.js, as well as tools like [Browserify](https://browserify.org/) and [Webpack](https://webpack.js.org/). 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 [Rollup](https://rollupjs.org/) or [Babel](https://babeljs.io/).

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.

A popular way for creating a bundle is to setup an npm script for [Webpack](https://webpack.js.org/). To install Webpack, run this from the command line:

2. Install required tools.
```bash
npm install webpack webpack-cli --save-dev
$ npm install mithril
$ npm install esbuild --save-dev
```

Open the `package.json` that you created earlier, and add an entry to the `scripts` section:

```json
{
"name": "my-project",
"scripts": {
"start": "webpack src/index.js --output bin/app.js -d --watch"
3. Add a "start" entry to the scripts section in `package.json`.
```json
{
"...": "...",
"scripts": {
"start": "esbuild index.js --bundle --outfile=bin/main.js --watch"
}
}
}
```

Remember this is a JSON file, so object key names such as `"scripts"` and `"start"` must be inside of double quotes.

The `-d` flag tells webpack to use development mode, which produces source maps for a better debugging experience.
```

The `--watch` flag tells webpack to watch the file system and automatically recreate `app.js` if file changes are detected.
Optionally, if you'd like to use JSX, you can use the `--jsx-factory` and `--jsx-fragment` flags with esbuild.

Now you can run the script via `npm start` in your command line window. This looks up the `webpack` command in the npm path, reads `index.js` and creates a file called `app.js` which includes both Mithril.js and the `hello world` code above. If you want to run the `webpack` command directly from the command line, you need to either add `node_modules/.bin` to your PATH, or install webpack globally via `npm install webpack -g`. It's, however, recommended that you always install webpack locally and use npm scripts, to ensure builds are reproducible in different computers.

```
npm start
```

Now that you have created a bundle, you can then reference the `bin/app.js` file from an HTML file:

```html
<html>
<head>
<title>Hello world</title>
</head>
<body>
<script src="bin/app.js"></script>
</body>
</html>
```

As you've seen above, importing a module in CommonJS is done via the `require` function. You can reference npm modules by their library names (e.g. `require("mithril")` or `require("jquery")`), and you can reference your own modules via relative paths minus the file extension (e.g. if you have a file called `mycomponent.js` in the same folder as the file you're importing to, you can import it by calling `require("./mycomponent")`).

To export a module, assign what you want to export to the special `module.exports` object:

```javascript
// mycomponent.js
module.exports = {
view: function() {return "hello from a module"}
}
```

In the `index.js`, you would then write this code to import that module:
```json
{
"...": "...",
"scripts": {
"start": "esbuild index.js --bundle --outfile=bin/main.js --jsx-factory=m --jsx-fragment='\"[\"' --watch"
}
}
```

4. Create `index.js` file.
```javascript
// index.js
var m = require("mithril")

var MyComponent = require("./mycomponent")

m.mount(document.body, MyComponent)
```

Note that in this example, we're using `m.mount`, which wires up the component to Mithril.js' autoredraw system. In most applications, you will want to use `m.mount` (or `m.route` if your application has multiple screens) instead of `m.render` to take advantage of the autoredraw system, rather than re-rendering manually every time a change occurs.

#### Production build

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 `package.json` and add a new npm script:

```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"
}
}
import m from "mithril";
m.render(document.getElementById("app"), "hello world");
```

You can use hooks in your production environment to run the production build script automatically. Here's an example for [Heroku](https://www.heroku.com/):

```json
{
"name": "my-project",
"scripts": {
"start": "webpack -d --watch",
"build": "webpack -p",
"heroku-postbuild": "webpack -p"
}
}
5. Create `index.html` file.
```html
<!DOCTYPE html>
<body>
<div id="app"></div>
<script src="bin/main.js"></script>
</body>
```

---

### Alternate ways to use Mithril.js

#### Live reload development environment

Live reload is a feature where code changes automatically trigger the page to reload. [Budo](https://github.com/mattdesl/budo) is one tool that enables live reloading.

6. Run your bundler script.
```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
$ npm run start
```

The source file `index.js` 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.

#### Vanilla

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:

```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>
```

```javascript
// index.js

// if a CommonJS environment is not detected, Mithril.js will be created in the global scope
m.render(document.body, "hello world")
```
7. Open `index.html` in a browser. You should see `hello world` rendered on your page.