Ember CLI Addons

This talk reviews the current (2014/09/25) hooks available to Ember CLI addons. What they do, how they work by default, and what the common use cases for each are.

Transcript

1. Ember CLI Addons
2. Who the heck is this guy? • DockYarder • Ember Core Team • General Open Source Addict twitter: rwjblue github: rwjblue
3. Thank You!!
4. What is Ember CLI?
5. What is Ember CLI? • Convention over Configuration • ES6 Modules • Blueprints/Generators • Test Harness • A Metric Crap-tonne more.
6. CLI == Command Line (duh) ember build <options...> ember generate <blueprint> <options...> ember new <app-name> <options...> ember serve <options...> ember test <options...>
8. Creating a Project npm install -g ember-cli ember new my-project cd my-project
9. Creating a Project % tree app -d app ├── components ├── controllers ├── helpers ├── models ├── routes ├── styles ├── templates │ └── components └── views
10. Creating a Project % tree tests -d tests ├── helpers └── unit
11. Creating a Project % ember server version: 0.0.46 Livereload server on port 35729 Serving on http://0.0.0.0:4200 Build successful - 444ms.
12. Generators % ember generate component async-select version: 0.0.46 installing create app/components/async-select.js create app/templates/components/async-select.hbs create tests/unit/components/async-select-test.js
13. Generators % cat app/components/async-select.js import Ember from 'ember'; export default Ember.Component.extend({ });
14. Generators import { test, moduleForComponent } from 'ember-qunit'; moduleForComponent('async-select'); test('it renders', function() { var component = this.subject(); equal(component.state, 'preRender'); this.append(); equal(component.state, 'inDOM'); });
15. Test Harness % ember test
16. Addons?
18. Addons - What can they do? • Pieces to a consuming application (Routes, Controllers, Views, Components, etc) • Development Server Middlewares • Blueprints (aka generators) • Configuration • Commands
19. Addons - What can they do? • Modify Built Assets • Update build output. • Preprocessors
20. What “hooks” are there?
21. Addon Infrastructure Hooks • constructor & init • config • blueprintsPath • includedCommands • serverMiddleware • postBuild
22. Addon Build Hooks • treeFor • included • postprocessTree
23. constructor & init • Constructor is called with the current project as an argument. • init is called just after the constructor • Default is to store `this.project`
24. config • Receives: ◦ Currently building environment ◦ Initial Application config • Can augment application config • Return an object to be merged with app • Defaults to using `config/environment.js`
25. config
26. blueprintsPath • No arguments • Return the path for blueprints • Defaults to `blueprints/` (if present)
27. blueprintsPath
28. includedCommands • No arguments • Return an object ◦ key - command name ◦ value - command instance or create options • No default implementation.
29. includedCommands
30. serverMiddleware • Receives an “options” argument: ◦ app -- express instance ◦ options ▪ project ▪ watcher ▪ environment • No default implementation.
31. serverMiddleware
32. serverMiddleware
33. postBuild • Receives the `result` object from build: ◦ directory -- path to build output • No default implementation
34. included • Called when the addon is included in a build • Receives the `EmberApp` instance as an arg • Generally used to call `app.import`
35. included
36. treeFor
38. • Returns a given type of tree (if present) • Merged with application tree of same type • Delegates to methods based on tree type • Returns default tree (based on type) if present treeFor
39. treeFor • Uses `addon.treePaths` object to determine paths on disk (relative to addon dir) for each tree type • Uses `addon.treeForMethods` object to determine which internal methods to call for a given type
40. treeFor • app • styles • templates • addon • vendor • test-support • public
41. treeForApp • Receives tree at `treePaths[‘app’]` (defaults to addons `app/` directory) • Return value is merged with the application’s app tree.
42. treeForStyles • Receives tree at `treePaths[‘styles’]` (defaults to addons `app/styles/` directory) • Return value is merged with the application’s styles tree (also `app/styles/`)
44. treeForTemplates • Receives tree at `treePaths[‘templates’]` (defaults to addons `app/templates/` directory) • Return value is merged with the application’s templates tree (also `app/templates/`)
45. treeForAddon • Receives tree at `treePaths[‘addon’]` (defaults to addons `addon/` directory) • Returned tree is build into a standalone package under the addon’s namespace. ◦ ES6 -> `vendor.js` ◦ Styles -> `vendor.css` ◦ Templates -> `vendor.js` ◦ JSHint (when developing addon)
46. treeForVendor • Receives tree at `treePaths[‘vendor’]` (defaults to addons `vendor/` directory) • Return value is merged with the application’s vendor tree (defaults to `vendor/`)
47. treeForTestSupport • Receives tree at `treePaths[‘test-support’]` (defaults to addons `test-support/` directory) • Return value is merged with the application’s test tree (generally in `test/`)
48. treeForPublic • Receives tree at `treePaths[‘public’]` (defaults to addons `public/` directory) • Return value is merged with the application’s public tree. • Default is to make addons `public/` nested under addon name in final `dist/`
49. postprocessTree • Receives 2 arguments: ◦ Type of post processing (currently only all) ◦ Receives tree after build • Output of processing all addons is returned from `app.toTree()`
50. Basic Guidelines • Keep all code in `addon/` • import and re-export in `app/` if needed (mostly for components and templates) • Allows extension of your addon • Allows easier unit testing
51. Discovery
53. Discovery • Search project dependencies ◦ Look for `ember-addon` in keywords • Search `package.json`’s `ember-addon` key for `paths`
54. Discovery - App
55. Discovery - Addon
56. Creating an Addon
57. Creating From outside of a project to create a new standalone addon: `ember addon my-foo` From within an existing project to create an in-repo addon: `ember generate in-repo-addon my-foo`
58. Creating - External
59. Creating - In Repo
60. Creating - Minimal Addon
61. Testing an Addon
62. Testing • Default generator creates a test app • Unit tests • Integration tests (against test/dummy app)
63. Testing - Unit
64. Testing - Acceptance
65. Testing - Acceptance
66. Dependencies
67. Dependencies SHOOT ME NOW!!!
68. Dependencies • NPM Package for “node-land” tooling • Bower Package for “browser-land” tooling • `bower.json` as a way for apps to override • Blueprint for addon name, for installing bower packages needed
69. Dependencies
70. Dependencies
71. Lets see it!
72. The End