6.3 KiB
Webpack!
Canvas is almost done transitioning from require_js to webpack. If you'd like, you can help. Canvas is currently equipped to run with either frontend build to make the transition painless as possible.
The philosophy is simple.
Step 1) Make Webpack able to build the canvas app as it is today, warts and all, while it can still run on the require_js build. This includes building and sending assets to the CDN on deployment.
-
test the heck out of the webpack version until we're sure the world isn't broken. With parameter-enabled webpack js loading, this can be done in all environments.
-
Start using webpack by default instead of require_js by default in all environments.
-
Leverage ES6, no AMD, etc in app code, and start deleting some of our crazy webpack loaders that were built to deal with some of the require-js specific hoops we ran into over the years.
Where things are
In order to make webpack able to consume our currently-somewhat-disorganized build structure, we've build a series of loaders and plugins for webpack that extend webpack to digest canvas JS and Coffeescript as-it-stands. These are all in the "frontend_build" folder, and are commented where it's deemed helpful.
The base webpack configuration is also in that folder (baseWebpackConfig.js). This is so that our normal webpack.config.js file can use the config as is, and the configuration files for test and production can simply extend to add or remove elements as necessary.
Building javascript with webpack
If you look at package.json, you can see there are 2 scripts for building your assets with webpack (webpack and webpack-production). If you want to include the translations (eg when you run webpack-production), make sure you've run "rake i18nliner:generate_js" first so translations are in place, webpack depends on those already existing. You can use these scripts with "yarn run":
yarn run webpack
This will build uncompressed js with eval'd sourcemaps, useful for development. It also runs webpack with the "--watch" option so as you continue to change things your updates will get compiled quickly.
yarn run webpack-production
This uglifies the resulting bundles, and takes longer. Don't use for development.
Running js tests with webpack
Lets say you are working on the “dashboard_cards” feature, just run:
yarn run jspec-watch spec/javascripts/jsx/dashboard_card
While you write code and it will have a watcher that catches
any changes and re-runs just the dashboard_card specs if you save any
file that went into it. It should run & reload in less than a few
seconds. You can give it the path to a specific spec file or have it
run an entire directory.
Or, if you are working on something that might touch a lot of stuff, run:
yarn run test-watch
and while you are changing stuff, it will run all the QUnit specs on
any change. It should only take a couple seconds for webpack to process
the file change and to reload the specs in the browser.
When karma starts, it automatically starts a webpack-dev-server and webpacks whatever it needs to run the tests. see karma.conf.js for more info on how it works.
To run all the tests, you can run:
yarn test
If you are using docker and want to run them all in a headless container you can do so with with:
docker-compose run --rm js-tests
which spools up the "js-tests" container specified in docker-compose.yml, which has an entry point that knows how to kick off karma with a headless runner.
Webpack Notifications
If you use macOS, you can setup system notifications for when the Webpack build starts and ends so that you don't have to constantly watch the terminal for it.
To do so, add the following to your .bashrc or .zshrc:
export ENABLE_CANVAS_WEBPACK_HOOKS=1
source ~/canvas-lms/frontend_build/webpackHooks/macNotifications.sh
macNotifications.sh simply defines some shell variables that Webpack will use
to execute commands on specific hooks during the build process.
If you use Linux, or would like to setup your own custom Webpack notifications,
you can take a at how macNotifications.sh works and write your own hooks.
FAQ!
I got some errors that look like "Cannot resolve module", but the module is totally there. What gives? We do a lot of path rewriting to find things that are buried in extensible areas in canvas. If you're working with a plugin, look at frontend_build/CompiledReferencePlugin.js for an example of how we look at some require statements and rewrite them to find the right file; see if you can apply those ideas to your own loader if need be.
Webpack says it can't find some "translations/" modules. What should I do?
Run rake i18n:generate_js. Webpack doesn't know how to generate the
translations files yet, though we may tackle that in the future. For now
that extract task needs to run before the first webpack build. When in doubt,
just run rake canvas:compile_assets for a fully up to date build.
TODO List (update as needed):
TASK LIST
[ ] convert the i18nliner task that extracts all the translations from source files to be a babel loader so you can work against the same ast that babel already made and so it can work against the es6 source and not the compiled output.
[X] ensure strings are still checked/exported w/o errors, i.e. rake i18n:check (it shells out to node stuffs)
[X] load up canvas w/ optimized js and RAILS_LOAD_ALL_LOCALES=1, switch your locale and ensure you see translations
[ ] extract duplicated loader code from i18nLinerHandlebars and emberHandlebars
[ ] in a separate commit extract i18nLinerHandlebars loader function and what it duplicates from prepare_hbs to a function both can use.
After we're on webpack in production:
[ ] re-work js.rake to do away with requirejs stuff
[ ] un-amd all vendor dependencies that we've wrapped AMD wrappers around
[ ] re-write screenreader gradebook in not-ember
[ ] change all references to "compiled" to "coffeeescript" and then do away with that loader
[ ] delete our custom require-js plugins
[ ] kill the auto-css-in-handlebars imports (make them explicit) and remove that loader
[ ] plugins that need to be extended should have explicit extension points and let plugin register itself
[ ] audit all loaders to find dumb things we had to do for require
[ ] {low-priority} in chunks, take AMD requires off of our js files
[ ] Use Jest for future JS tests