babel / website

:globe_with_meridians: The Babel documentation website

babel/website

This is the source for the babeljs.io website; feel free to suggest changes to our docs!

• Current: main branch is deployed to https://babeljs.io
• Old: old-site branch is deployed to https://v6.babeljs.io

Setup

Node: Check that Node is installed with version 10.19.0 and up. You can check this with node -v.

Yarn: Make sure that Yarn 1 is installed with version >= 1.19.0.

$ git clone [email protected]:babel/website.git
$ cd website
$ yarn && yarn bootstrap

• Just run yarn start next time (check the package.json for scripts).

Contributing to the website

To keep documentation in sync across all of Babel's packages, the docs are now directly located in this repository. The READMEs in babel/babel are auto generated and point to this documentation.

You might want to make yourself familiar with docusaurus to make significant changes to the website.

Looking for support?

For questions and support on contributing please join our Slack community, channel #website or directly here.

website's Issues

Docs: Using Modules

Details about bundling modules with browserify/webpack/etc. ie. modules: system only transpiles to the system.js syntax but doesn't bundle them with system.js

Blog Post: Using 6to5 with JSX/Flow

REPL: Examples

Previous there was a dropdown where you could select a bunch of ES6 examples and insert them into the console, although I never finished it and removed it so I could release the new site.

REPL: Better url escaping

encodeUriComponent doesn't escape parenthesis (and other characters) so people adding links to markdown end up giving it an incorrect link:

http://6to5.org/repl/#?experimental=true&playground=true&evaluate=true&code=%20%20%20%20function%20*traverse(value)%20%7B%0A%20%20%20%20%20%20if%20(typeof%20value%20

Merge usage/options to usage/cli

I think
http://6to5.org/docs/usage/options/
should be a sub-section of #6to5:
http://6to5.org/docs/usage/cli/#6to5

This makes for better navigation flow in reading the docs.

---

If the options is a separate page, it isn't really clear that some options aren't available in 6to5-node command (e.g. blacklist).

REPL: Improve REPL State Management

Currently, the REPL saves its state as an encoded URI in the address bar URL. This has several drawbacks including things like tricky escaping (i.e. #44) and unfriendly URLs (i.e. #162).

The goal of this enhancement is to leverage an external store for saving REPL state, if desired. Some requirements:

• URLs for saved REPL sessions should be friendly/short, for easy sharing.
• Persistence should be opt-in (i.e. every REPL session doesn't need to be saved somewhere)
• The persistence of state should be throttled, either by debouncing input or by explicitly asking the user to click a button to 'Save' the REPL state, useful for sharing or returning to at a later time.
• Consider how this ties into local storage persistence (implemented via #77).

Non requirements/goals:

• Private persistence (i.e. only certain users can access REPL sessions). That is way overboard right now.

Some ideas:

• Use the GitHub Gists API to persist REPL input.
• Use the JS Bin API to persist REPL input.

Better documentation for usage/api

http://6to5.org/docs/usage/api/

Ref: babel/babel#417

Include corresponding transformer names in the Tour?

The "Standard" entries on https://6to5.org/docs/usage/transformers/ link directly to sections of http://6to5.org/docs/tour/
It might be useful to have the sections of the Tour page mention the names of the corresponding transformers somehow, e.g. have http://6to5.org/docs/tour/#arrows mention arrowFunctions

Docs: Add detail to Register Options

http://6to5.org/docs/usage/require/#register-options

It should note that you can also pass in all of the options from http://6to5.org/docs/usage/options/.

@DylanPiercey was asking in chat about playground and experimental in particular.

Blog Post: Top 10 reasons to use 6to5

I've been asked for something like this by a few people now.

"⌘" OS X-ism

In the callout at the top of https://6to5.org/docs/setup/ :

and ⌘ + F whatever you're looking for.

Non-OS X users could get mildly confused by this 😈

Move script files to end of <body>

Docs: Optional fast transformers

• forOfFast
• classesFastSuper

3.0.0

• Publish to npm
• Update website
• Upgrade plugins
  • webpack
  • jest
  • ember-cli
  • broccoli
  • metalsmith
  • gulp
  • gobble
  • brunch
  • browserify
  • karma
  • duo
  • grunt
  • jade
  • connect
  • rails

REPL: console.log improvements

console.log(Function); // nothing is logged in the page's console.

https://github.com/6to5/6to5.github.io/blob/d7c38116c9c834fd6a6f32e79715e8b8a97530de/scripts/repl.js#L88

Don't collapse the sidebar

It's weird to have the sidebar constantly opening and closing when you're scrolling and it makes it awkward to select items.

forOf loose description is ungrammatical

The result is that are put in a fast path,

You seem to have accidentally a word after "that".

Blog Post: Authoring in io.js, publishing for npm

Haven't worked out the contents of this yet, but it's something along the lines of this:

• io.js adds support for a lot of ES6 features and can still publish to npm
• however if you want to remain compatible with Node.js you'll need to distribute a transpiled version of your library
• here's a couple simple ways to do it with 6to5

Ref: @brianleroux https://twitter.com/brianleroux/status/554751754701524992

Docs: Resources page

We should begin collecting third party blog posts/meetup videos/etc. about both ES6 and 6to5.

Fix links

http://validator.w3.org/checklink?uri=http%3A%2F%2F6to5.org%2F&hide_redirects=on&hide_type=all&depth=10&check=Check

Repl adding &=undefined to url

?experimental=true&playground=false&evaluate=true&loose=false&=undefined&code=

Ping @sparty02

REPL log output is not displayed when inside async function

Odd.
It seems the console.log is being ignored by the REPL output when we call it inside an async function.
I took too long to figure out the code was working but just was not displaying the log in the REPL.
In the browser dev tools it works well, i mean, the log appear.

The code i was trying:

function p1() {
  return new Promise(function(resolve, reject){
    setTimeout(function() {
      resolve('p1');
    }, 300);
  });
}

async function getVal() {
  var val1 = await p1();
  return val1;
}

(async function() {
  var bla = await getVal();
  console.log(bla); 
}());

More whitespace!

For example http://6to5.org/docs/usage/transformers/#self-contained is quite crowded.

REPL: Add support for all Babel options

It'd be nice to have a dropdown or something that allowed you to toggle all the options for 6to5. It'd be even nicer if it was auto generated from the latest 6to5.

"no runtime"?

The 6to5 site states:

Maps directly to the equivalent ES5 with no runtime

What does "no runtime" mean in this context? When I use ES6 class syntax I get a few extra helpers in the generated code:

var _get = function get(object, property, receiver) {
  var desc = Object.getOwnPropertyDescriptor(object, property);

  if (desc === undefined) {
    var parent = Object.getPrototypeOf(object);

    if (parent === null) {
      return undefined;
    } else {
      return get(parent, property, receiver);
    }
  } else if ("value" in desc && desc.writable) {
    return desc.value;
  } else {
    var getter = desc.get;
    if (getter === undefined) {
      return undefined;
    }
    return getter.call(receiver);
  }
};

var _inherits = function (subClass, superClass) {
  if (typeof superClass !== "function" && superClass !== null) {
    throw new TypeError("Super expression must either be null or a function, not " + typeof superClass);
  }
  subClass.prototype = Object.create(superClass && superClass.prototype, {
    constructor: {
      value: subClass,
      enumerable: false,
      writable: true,
      configurable: true
    }
  });
  if (superClass) subClass.__proto__ = superClass;
};

var _prototypeProperties = function (child, staticProps, instanceProps) {
  if (staticProps) Object.defineProperties(child, staticProps);
  if (instanceProps) Object.defineProperties(child.prototype, instanceProps);
};

Admittedly this is a very small amount of extra code, but is that code not considered a "runtime"? If not, what would you consider to be a runtime? Do you mean some actual sort of VM?

Add documentation for all options

Ref: babel/babel#414

FR: Resizable console and error divs.

It would be easier to read them, when they are more than a line.

//cc @thejameskyle

favicon

Needs to have a favicon, as this isn't great:

Setup: Nodemon

$ nodemon --exec 6to5-node --experimental path/to/script.js

Ref: babel/babel#279

Compare: Move React / JSX to new section

Having React and JSX in the "Language Support" section seems weird. Mainly since everything else is new JS features it seems like a cheap shot at the other transpilers because supporting react/jsx is unique to 6to5.

Perhaps a new section could be added where this could go. I'm don't really have a name in mind.

IE8 Support

6to5 supports IE8 for most things, but our website doesn't and I don't think it would be difficult to.

REPL output doesn't match command line output

Given this code:

class User extends Model {
  constructor() {
    super();
    this.sayHello();
  }

  sayHello() {
    alert("Hello World!");
  }
}

The REPL should produce:

var User = function User() {
  Model.call(this);
  this.sayHello();
};

_inherits(User, Model);

User.prototype.sayHello = function () {
  alert("Hello World!");
};

It actually produces:

var User = (function (Model) {
  function User() {
    _get(Object.getPrototypeOf(User.prototype), "constructor", this).call(this);
    this.sayHello();
  }

  _inherits(User, Model);

  _prototypeProperties(User, null, {
    sayHello: {
      value: function () {
        alert("Hello World!");
      },
      writable: true,
      enumerable: true,
      configurable: true
    }
  });

  return User;
})(Model);

Header breaks on tablets

Module formats should include links to their respective websites

e.g. https://6to5.org/docs/usage/modules/#umd should include a link to https://github.com/umdjs/umd

Tour: Async Functions

There's currently a very small note about them here: http://thejameskyle.com/6to5.github.io/docs/tour/#generators

@monsanto pointed out they should have their own section.

Auto-deploy when new 6to5 releases are made

FR: Local storage for REPL.

Was planning to add this feature of saving input.editor.getValue(); to localstore.

If query.code found display it or else fetch and display the local store data.

What say @sebmck @thejameskyle ?

REPL: Include Source Maps?

Thought: Including source maps in the transpiled REPL output would allow browser debugging through the ES6 (REPL input) vs ES5 (REPL output) code.

Add notice about not supporting short-hand destructured defaults to caveats section.

See babel/babel#230 for tracking issue, also acornjs/acorn#181.

Shorthand like

let { a = 5 } = {};

does not work, yet the following does.

let { a: a = 5 } = {};

Docs: Regenerator

There's currently nothing 😢

Better selfContained docs

Document the need for a module bundler, webpack, browserify etc and provide details on installing 6to5-runtime.

Clarify what "no runtime" actually means

REPL fails to update URL hash when the code throws an error

At least, when I paste this

if (let x = 5) { console.log(x) }

into the REPL, the url never changes, and the left side throws an error.

on Chrome 39.0.2171.99 (and some version of Chrome 40 < 40.0.2214.91)

Blog Post: How 6to5 works

Needs more information: How does one selectively include polyfills?

This statement

You may alternatively selectively include what you need:

which can be found in the polyfills section needs some clarification.

How would one go about selectively including what you need? Do you hunt for the packages yourself? It doesn't seem possible with 6to5 but it would be nice perhaps as a part of https://github.com/zloirock/core-js

Fix readable code example on homepage

The current readable example of

class User extends Model {
  constructor() {
    super();
    this.sayHello();
  }

  sayHello() {
    alert("Hello World!");
  }
}

to

var User = function User() {
  Model.call(this);
  this.sayHello();
};

_inherits(User, Model);

User.prototype.sayHello = function () {
  alert("Hello World!");
};

is hilariously out of date.

Is 6-to-library worth spreading the word?

Hello,

I wrote the formatter 6-to-library. Do you think it's worth a mention somewhere in the docs?

Why?

I wanted to author in ES6, and still deliver a seamless experience to users today. The UMD formatter does its job well. But it has no support for simple globals, and always exports exports by name. I wanted to avoid the need for explicitly saying require('a-library').default when only the default key is exported.

Broken Link on Usage/Browser Page

On: https://6to5.org/docs/usage/browser/

The 'setup build systems' link below is broke.

Not intended for serious use

Compiling in the browser has a fairly limited use case, so if you are working on a production site you should be precompiling your scripts server-side. See setup build systems for more information.

Add cache busting

?t=timestamp at the end of all the resources.

Add async functions to Tour