Fix docs (#2482)
* Fix #2414, address part of #1687 Also cleared the CSS up to be a lot more readable instead of smooshed into a single line. * Redo the testing docs page - Addresses another part of #1687 - Also, fix a few linter issues in the ospec binary * Add note about third-party cookies, tweak a line * Make the JSX comparison much more meaningful And let the code speak for itself. Don't fuel the flame wars any more than what they've already become. We should be *unopinionated*, and so I've updated those docs to remove the existing opinion. * Remove a bunch of outdated ES6 references * Remove the CSS page
This commit is contained in:
Isiah Meadows
GitHub
parent
61b087ea20
commit
20f0759103
11 changed files with 525 additions and 283 deletions
115
docs/es6.md
115
docs/es6.md
|
|
@ -1,71 +1,117 @@
|
|||
# ES6
|
||||
# ES6+ on legacy browsers
|
||||
|
||||
- [Setup](#setup)
|
||||
- [Using Babel with Webpack](#using-babel-with-webpack)
|
||||
|
||||
---
|
||||
|
||||
Mithril is written in ES5, and is fully compatible with ES6 as well. ES6 is a recent update to JavaScript that introduces new syntax sugar for various common cases. It's not yet fully supported by all major browsers and it's not a requirement for writing an application, but it may be pleasing to use depending on your team's preferences.
|
||||
Mithril is written in ES5, but it's fully compatible with ES6 and later as well. All modern browsers do support it natively, up to and even including native module syntax. (They don't support Node's magic module resolution, so you can't use `import * as _ from "lodash-es"` or similar. They just support relative and URL paths.) And so you can feel free to use [arrow functions for your closure components and classes for your class components](components.md).
|
||||
|
||||
In some limited environments, it's possible to use a significant subset of ES6 directly without extra tooling (for example, in internal applications that do not support IE). However, for the vast majority of use cases, a compiler toolchain like [Babel](https://babeljs.io) is required to compile ES6 features down to ES5.
|
||||
But, if like many of us, you still need to support older browsers like Internet Explorer, you'll need to transpile that down to ES5, and this is what this page is all about, using [Babel](https://babeljs.io) to make modern ES6+ code work on older browsers.
|
||||
|
||||
---
|
||||
|
||||
### Setup
|
||||
|
||||
The simplest way to setup an ES6 compilation toolchain is via [Babel](https://babeljs.io/).
|
||||
First, if you haven't already, make sure you have [Node](https://nodejs.org/en/) installed. It comes with [npm](https://www.npmjs.com/) pre-bundled, something we'll need soon.
|
||||
|
||||
Babel requires NPM, which is automatically installed when you install [Node.js](https://nodejs.org/en/). Once NPM is installed, create a project folder and run this command:
|
||||
Once you've got that downloaded, open a terminal and run these commands:
|
||||
|
||||
```bash
|
||||
npm init -y
|
||||
# Replace this with the actual path to your project. Quote it if it has spaces,
|
||||
# and single-quote it if you're on Linux/Mac and it contains a `$` anywhere.
|
||||
cd "/path/to/your/project"
|
||||
|
||||
# If you have a `package.json` there already, skip this command.
|
||||
npm init
|
||||
```
|
||||
|
||||
If you want to use Webpack and Babel together, [skip to the section below](#using-babel-with-webpack).
|
||||
Now, you can go one of a couple different routes:
|
||||
|
||||
To install Babel as a standalone tool, use this command:
|
||||
- [Use Babel standalone, with no bundler at all](#using-babel-standalone)
|
||||
- [Use Babel and bundle with Webpack](#using-babel-with-webpack)
|
||||
|
||||
#### Using Babel standalone
|
||||
|
||||
First, we need to install a couple dependencies we need.
|
||||
|
||||
- `@babel/cli` installs the core Babel logic as well as the `babel` command.
|
||||
- `@babel/preset-env` helps Babel know what to transpile and how to transpile them.
|
||||
|
||||
```bash
|
||||
npm install @babel/cli @babel/preset-env --save-dev
|
||||
```
|
||||
|
||||
Create a `.babelrc` file:
|
||||
Now, create a `.babelrc` file and set up with `@babel/preset-env`.
|
||||
|
||||
```json
|
||||
{
|
||||
"presets": ["@babel/preset-env"]
|
||||
"presets": ["@babel/preset-env"],
|
||||
"sourceMaps": true
|
||||
}
|
||||
```
|
||||
|
||||
To run Babel as a standalone tool, run this from the command line:
|
||||
And finally, if you have *very* specific requirements on what you need to support, you may want to [configure Browserslist](https://github.com/browserslist/browserslist) so Babel (and other libraries) know what features to target.
|
||||
|
||||
*By default, if you don't configure anything, Browserslist uses a fairly sensible query: `> 0.5%, last 2 versions, Firefox ESR, not dead`. Unless you have very specific circumstances that require you to change this, like if you need to support IE 8 with a lot of polyfills, don't bother with this step.*
|
||||
|
||||
Whenever you want to compile your project, run this command, and everything will be compiled.
|
||||
|
||||
```bash
|
||||
babel src --out-dir bin --source-maps
|
||||
babel src --out-dir dist
|
||||
```
|
||||
|
||||
You may find it convenient to use an npm script so you're not having to remember this and typing it out every time. Add a `"build"` field to the `"scripts"` object in your `package.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"build": "babel src --out-dir dist"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
And now, the command is a little easier to type and remember.
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
#### Using Babel with Webpack
|
||||
|
||||
If you're already using Webpack as a bundler, you can integrate Babel to Webpack by following these steps.
|
||||
If you want to use Webpack to bundle, it's a few more steps to set up. First, we need to install all the dependencies we need for both Babel and Webpack.
|
||||
|
||||
- `webpack` is the core Webpack code and `webpack-cli` gives you the `webpack` command.
|
||||
- `@babel/core` is the core Babel code, a peer dependency for `babel-loader`.
|
||||
- `babel-loader` lets you teach Webpack how to use Babel to transpile your files.
|
||||
- `@babel/preset-env` helps Babel know what to transpile and how to transpile them.
|
||||
|
||||
```bash
|
||||
npm install @babel/core babel-loader @babel/preset-env --save-dev
|
||||
npm install webpack webpack-cli @babel/core babel-loader @babel/preset-env --save-dev
|
||||
```
|
||||
|
||||
Create a `.babelrc` file:
|
||||
Now, create a `.babelrc` file and set up with `@babel/preset-env`.
|
||||
|
||||
```json
|
||||
{
|
||||
"presets": ["@babel/preset-env"]
|
||||
"presets": ["@babel/preset-env"],
|
||||
"sourceMaps": true
|
||||
}
|
||||
```
|
||||
|
||||
Next, create a file called `webpack.config.js`
|
||||
Next, if you have *very* specific requirements on what you need to support, you may want to [configure Browserslist](https://github.com/browserslist/browserslist) so Babel (and other libraries) know what features to target.
|
||||
|
||||
*By default, if you don't configure anything, Browserslist uses a fairly sensible query: `> 0.5%, last 2 versions, Firefox ESR, not dead`. Unless you have very specific circumstances that require you to change this, like if you need to support IE 8 with a lot of polyfills, don't bother with this step.*
|
||||
|
||||
And finally, set up Webpack by creating a file called `webpack.config.js`.
|
||||
|
||||
```javascript
|
||||
const path = require('path')
|
||||
|
||||
module.exports = {
|
||||
entry: './src/index.js',
|
||||
entry: path.resolve(__dirname, 'src/index.js'),
|
||||
output: {
|
||||
path: path.resolve(__dirname, './bin'),
|
||||
path: path.resolve(__dirname, 'dist'),
|
||||
filename: 'app.js',
|
||||
},
|
||||
module: {
|
||||
|
|
@ -78,32 +124,40 @@ module.exports = {
|
|||
}
|
||||
```
|
||||
|
||||
This configuration assumes the source code file for the application entry point is in `src/index.js`, and this will output the bundle to `bin/app.js`.
|
||||
This configuration assumes the source code file for the application entry point is in `src/index.js`, and this will output the bundle to `dist/app.js`.
|
||||
|
||||
To run the bundler, setup an npm script. Open `package.json` and add this entry under `"scripts"`:
|
||||
Now, to run the bundler, you just run this command:
|
||||
|
||||
```bash
|
||||
webpack -d --watch
|
||||
```
|
||||
|
||||
You may find it convenient to use an npm script so you're not having to remember this and typing it out every time. Add a `"build"` field to the `"scripts"` object in your `package.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-project",
|
||||
"scripts": {
|
||||
"start": "webpack -d --watch"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You can now then run the bundler by running this from the command line:
|
||||
And now, the command is a little easier to type and remember.
|
||||
|
||||
```bash
|
||||
npm start
|
||||
```
|
||||
|
||||
#### Production build
|
||||
For production builds, you'll want to minify your scripts. Luckily, this is also pretty easy: it's just running Webpack with a different option.
|
||||
|
||||
To generate a minified file, open `package.json` and add a new npm script called `build`:
|
||||
```bash
|
||||
webpack -p
|
||||
```
|
||||
|
||||
You may want to also add this to your npm scripts, so you can build it quickly and easily.
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-project",
|
||||
"scripts": {
|
||||
"start": "webpack -d --watch",
|
||||
"build": "webpack -p"
|
||||
|
|
@ -111,11 +165,16 @@ To generate a minified file, open `package.json` and add a new npm script called
|
|||
}
|
||||
```
|
||||
|
||||
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/):
|
||||
And then running this is a little easier to remember.
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
And of course, you can do this in automatic production build scripts, too. Here's how it might look if you're using [Heroku](https://www.heroku.com/), for example:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-project",
|
||||
"scripts": {
|
||||
"start": "webpack -d --watch",
|
||||
"build": "webpack -p",
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue