language-babel

JavaScript ES201x, React JSX, Flow and GraphQL Grammar. Babel Transpiler

gandm

2,201,097

1,007

2.85.0

MIT

GitHub

This package provides the following services:

language-babel

Build Status Build status Build Dependencies

Language grammar for all versions of JavaScript including ES2016 and ESNext, JSX syntax as used by Facebook React, Atom's etch and others, as well as optional typed JavaScript using Facebook flow. This package also supports highlighting of GraphQL language constructs when inside certain JavaScript template strings. For .graphql and .gql file support please see language-graphql . The colour of syntax is determined by the theme in use.

The package also provides

By default the language-babel package will detect file types .js,.babel,.jsx, .es, .es6, .mjs and .flow. Use the standard ATOM interface to enable it for other file types. This provides a grammar that scopes the file in order to colour the text in a meaningful way. If other JavaScript grammars are enabled these may take precedence over language-babel. Look at the bottom right status bar indicator to determine the language grammar of a file being edited. language-babel will be shown as either Babel or Babel ES6 JavaScript. Clicking the name will allow the grammar for a file to be changed.

language-babel provides Babel V6 & V5 transpiler support. If you only require grammar/syntax highlighting ensure that the package settings Transpile On Save and Allow Local Override are both off.

Installation

Install via ATOM or by using apm install language-babel. If you only need to use the provided grammar read no further!

Auto Completion of JSX tags, elements and attributes

JSX tag closures are provided as auto-complete options. In addition, common HTML elements and their associated properties are displayed as auto-complete lists. Those supported by language-babel are described here

autoclose

Commenting out JSX elements

JSX elements cannot be commented out by using standard // or /* */ commenting. Normally {/* */} is used instead. language-babel changes the Atom toggle comments behaviour when inside a JSX block to support this behaviour. Nested elements within JSX that require a // form of commenting will be detected automatically.

autoclose

Automatic insertion between JSX tags

When a newline is inserted between a matched open/close pair of JSX tags, language-babel inserts an additional line and positions the cursor. If Auto Indent is also turned on then the cursor is correctly indented.

autoclose

Automatic Indenting of JSX

The package setting Auto Indent JSX if enabled will auto-indent any JSX code typed or moved across using suitable Atom defaults. There are also three commands - language-babel:toggle-auto-indent-jsx, language-babel:auto-indent-jsx-on and language-babel:auto-indent-jsx-off that override the default behaviour. These can be mapped to keyboard shortcuts if needed.

Auto-Indenting will also attempt to read the .eslintrc file associated with an edited file's project for the presence of four properties whose defaults are shown below. These rules, which are part of the ESLint-plugin-React EsLint plugin, are then used to determine the alignment and tab/spaces spacing of JSX elements. For more information on the options for these rules see Closing bracket, Indent and Indent Props.

Please note that no attempt is currently made to read eslint settings in any other file. e.g. package.json, eslint.js, extends..., etc.

{
  "rules": {
    "indent": 1,
    "react/jsx-closing-bracket-location": 1,
    "react/jsx-indent-props": 1,
    "react/jsx-indent": 1
  }
}

When moving around a JSX block language-babel reformats the preceding JSX lines automatically. Lines following the cursor are not indented. This is to protect the source code following incomplete JSX from being processed. The user should correctly position the first JSX element as auto-indenting will not do this.

You may also turn off automatic indenting for all files by setting the package option Auto Indent JSX

indent

Interface to Babel v7, v6 & v5.

language-babel fully supports the Babel JavaScript transpiler versions 5, 6 and 7.

Options in the language-babel package settings and/or in .languagebabel project based JSON files allow for Babel validations to be carried out on a file saves using .babelrc options. A file tree context menu - Language-Babel - is also provided that allows whole directories to be transpiled obeying any .babelrc and .languagebabel settings. Even if using a workflow such as gulp, webpack, etc, this can be very useful. Additional options allow the output from Babel (transpiled code and maps ) to be output to other directories.

It is also possible to preview any source file as Babel would output it.

Previewing

Babel code can be previewed as shown below. Source mapping keeps the ES201x file's cursor in step with the transpiled code's cursor. This feature requires the Atom package source-preview in which language-babelbecomes a provider of transpiled output which source-preview consumes.

Please note that the following two packages should be disabled or uninstalled to stop multiple packages contending for the same transpile - source-preview-babel and source-preview-react.

source-preview provides a keyboard toggle to view the current file. As with transpiling described below, a project must have the relevant .babelrc, package.json and node_modules

example

Transpiling

This package works by using the concept of a project folder which we assume contains a project or even nested projects any of which may contain a Babel project. In a Babel project, we expect to see one or more .babelrc files, node_modules folders at the root's of the project containing an optional @babel/core babel-core and other babel plugins/presets as determined by the project's package.json file. In addition, we may expect to see one or more .languagebabel files in the project. Projects are either implicit (an Atom project folder) or explicit (denoted by a .languagebabel property of "projectRoot": true). If no @babel/core or babel-core is found in the project then a check is made to determine if this is part of a Yarn workspace and if so a further check is made in the workspace node_modules for @babel/core or babel-core. If none are found then a version will be provided by language-babel but this will be a Babel Version 6 instance. Plugins and presets will not be provided by the package.

A trivial example project that shows examples of using .languagebabel and .babelrc files may be found here.

example

Multiple projects may be open at any time inside Atom and language-babel must allow the use of differing babel-core versions and associated plugins when transpiling. It does this by using background tasks - one per Babel project. When a language-babel grammar enabled file is saved the package settings and optionally any .languagebabel configuration files are read to determine if the file should be transpiled and what to do with the output. These settings and .languagebabel options are described below.

It is very easy to ensure that language-babel does not transpile files that are not needed. Just turn off the global package setting Transpile On Save and turn on Allow Local Override. Apart from grammar highlighting only projects having a .languagebabel in the file path will then be affected by this package. Further granularity is easy too.

If .babelrc and/or package.json files contain Babel properties that are environment specific these environments should be created before Atom is started. In particular, Babel assumes a development environment by default, whereas Atom assumes a production environment by default.

e.g.

Windows

set NODE_ENV="development"
atom

OSX/Unix

NODE_ENV="development"
atom

Package Settings

For most projects, it is better to configure language-babel via project-based .languagebabel file properties which will override the package settings below. See ".langeuagebabel Configuration" for more information on this behaviour.

.languagebabel Configuration

.languagebabel JSON configuration files can exist in any directory of the path that contains a source file to be compiled. The properties in this file override the global package settings above. If .languagebabel files are present, they read and merged starting in the source files directory up to the project root directory. Properties defined closest the source file take precedence.

To use this option please enable the Allow Local Override package setting.

A .languagebabel file may contain one or more of the following properties.

{
  "babelMapsPath":                    "relPath",
  "babelMapsAddUrl":                  true|false,
  "babelSourcePath":                  "relPath",
  "babelTranspilePath":               "relPath",
  "createMap":                        true|false,
  "createTargetDirectories":          true|false,
  "createTranspiledCode":             true|false,
  "disableWhenNoBabelrcFileInPath":   true|false,
  "keepFileExtension":                true|false,
  "projectRoot":                      true|false,  
  "suppressSourcePathMessages":       true|false,
  "suppressTranspileOnSaveMessages":  true|false,
  "transpileOnSave":                  true|false
}

GraphQL Code Highlighting

language-babel supports highlighting of GraphQL code within JavaScript files. For highlighting .graphql and .gql files see its sister grammar - language-graphql.

Inside JavaScript, GraphQL enclosed in back-ticks, a.k.a. Quasi or template strings are highlighted. Other GraphQL structures, notably types, are supported by the Flow component of this package.

Strings that have one of three prefixes/tags are parsed by the grammar to highlight the code enclosed.

Relay.QL`This is how Relay uses template strings`

graphql`This is how Relay will use template strings`

gql`This is how Apollo for GraphQL uses template strings`

/* GraphQL */`For cases where no template tag function is available`

An example of using the third method for highlighting code using /* GraphQL */

var { graphql, buildSchema } = require('graphql');

var schema = buildSchema(/* GraphQL */`
  type Query {
    hello: String
  }
`);