111 lines
3.8 KiB
ReStructuredText
111 lines
3.8 KiB
ReStructuredText
JavaScript in edx-platform
|
|
==========================
|
|
|
|
ES2015
|
|
------
|
|
|
|
All new JavaScript code in edx-platform should be written in ES2015.
|
|
ES2015 is not a framework or library -- rather, it is the latest and
|
|
greatest revision of the JavaScript language itself, natively supported
|
|
in all modern browsers and engines. Think of it as JavaScript's
|
|
equivalent to Python 3. ES2015 brings with it number of wonderful
|
|
syntactic features, such as classes, native imports, arrow functions,
|
|
and new data structures. To learn more about ES2015, check out `Luke
|
|
Hoban's comprehensive ES6 Features
|
|
repo <https://github.com/lukehoban/es6features>`__.
|
|
|
|
Although ES2015 is natively supported in modern browsers, older browsers
|
|
can't interpret it. Here at edX, we support the two latest versions of
|
|
every browser, plus IE11, so we need to do a little extra work to
|
|
support ES2015. This is where Webpack and Babel come in. Webpack is a
|
|
module bundler that transforms, minifies, and compiles frontend code
|
|
into pre-built "bundles" to include within pages. It works together with
|
|
Babel to transpile ES2015 code into ES5 code, which can safely be used
|
|
in all browsers.
|
|
|
|
Fortunately, you don't need to worry about the gritty details of Webpack
|
|
in order to write ES2015 code. You just need to make sure Webpack knows
|
|
where to find your files. It's also important to note that **Webpack is
|
|
not compatible with RequireJS**. Work is currently underway to move all
|
|
legacy RequireJS modules into Webpack, but until it is complete, you
|
|
will need to update legacy code yourself in order to use it with ES2015.
|
|
|
|
Adding a New ES2015 Module
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Don't mix ES2015 and ES5 modules within directories. If necessary,
|
|
create a new directory just for your new file. If you create a new
|
|
directory, run the following from edx-platform root to copy over an
|
|
appropriate eslint config:
|
|
|
|
::
|
|
|
|
cp cms/static/js/features_jsx/.eslintrc.js path/to/your/directory
|
|
|
|
Give your new file an UpperCamelCase filename, such as
|
|
``MyAwesomeModule.js``. If it is a React module, use the ``.jsx``
|
|
extension; otherwise, use the ``.js`` extension.
|
|
|
|
If you intend to include this module itself directly within a page, you
|
|
will need to tell Webpack about it. Add a line to the ``entry`` object
|
|
within ``webpack.common.config.js``.
|
|
|
|
::
|
|
|
|
'MyAwesomeModule': 'path/to/your/directory/MyAwesomeModule.js',
|
|
|
|
The new entry's key should be the name of your module (typically this is
|
|
the same as your filename), and its value should be the path to your
|
|
file relative to the edx-platform root.
|
|
|
|
Writing Your File
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
Structure your module using ``class``\ es. Typically, you'll want to
|
|
define and export one ``class`` per file. If you are going to be
|
|
including this module directly within a page and passing it through
|
|
Webpack, use a non-default export. ``MyAwesomeModule.js`` should look
|
|
something like this:
|
|
|
|
::
|
|
|
|
export class MyAwesomeModule {
|
|
// your awesome code here
|
|
}
|
|
|
|
Use two-space indentation. This is industry standard practice for
|
|
ES2015. If you need to pull in external dependencies, use ``import``
|
|
statements:
|
|
|
|
::
|
|
|
|
import moment from 'moment';
|
|
import 'jquery.cookie';
|
|
import { MyOtherModule } from './MyOtherModule';
|
|
|
|
Building Your File
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
Devstack comes with two watcher containers specifically for building
|
|
assets. They compile frontend files very quickly, so you can see your
|
|
changes reflected in a browser almost immediately. You can run these
|
|
containers with:
|
|
|
|
::
|
|
|
|
make dev.up.watchers
|
|
|
|
and stop them with
|
|
|
|
::
|
|
|
|
make stop.watchers
|
|
|
|
If you make any changes to ``webpack.common.config.js`` while the
|
|
watchers are running, you will need to restart the watchers in order for
|
|
them to pick up your changes.
|
|
|
|
If your changes aren't being reflected in the browser, check the logs
|
|
with ``make logs`` to see if something went wrong. If you get stuck, ask
|
|
for help in the FedX hipchat room, or in #front-end on Slack.
|