Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Ember CLI Addons

Robert Jackson
September 25, 2014

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.

Robert Jackson

September 25, 2014
Tweet

More Decks by Robert Jackson

Other Decks in Technology

Transcript

  1. Ember CLI Addons

    View full-size slide

  2. Who the heck is this guy?
    ● DockYarder
    ● Ember Core Team
    ● General Open Source Addict
    twitter: rwjblue
    github: rwjblue

    View full-size slide

  3. What is Ember CLI?

    View full-size slide

  4. What is Ember CLI?
    ● Convention over Configuration
    ● ES6 Modules
    ● Blueprints/Generators
    ● Test Harness
    ● A Metric Crap-tonne more.

    View full-size slide

  5. CLI == Command Line (duh)
    ember build
    ember generate
    ember new
    ember serve
    ember test

    View full-size slide

  6. Creating a Project
    npm install -g ember-cli
    ember new my-project
    cd my-project

    View full-size slide

  7. Creating a Project
    % tree app -d
    app
    ├── components
    ├── controllers
    ├── helpers
    ├── models
    ├── routes
    ├── styles
    ├── templates
    │ └── components
    └── views

    View full-size slide

  8. Creating a Project
    % tree tests -d
    tests
    ├── helpers
    └── unit

    View full-size slide

  9. 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.

    View full-size slide

  10. 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

    View full-size slide

  11. Generators
    % cat app/components/async-select.js
    import Ember from 'ember';
    export default Ember.Component.extend({
    });

    View full-size slide

  12. 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');
    });

    View full-size slide

  13. Test Harness
    % ember test

    View full-size slide

  14. Addons - What can they do?
    ● Pieces to a consuming application
    (Routes, Controllers, Views, Components, etc)
    ● Development Server Middlewares
    ● Blueprints (aka generators)
    ● Configuration
    ● Commands

    View full-size slide

  15. Addons - What can they do?
    ● Modify Built Assets
    ● Update build output.
    ● Preprocessors

    View full-size slide

  16. What “hooks” are there?

    View full-size slide

  17. Addon Infrastructure Hooks
    ● constructor & init
    ● config
    ● blueprintsPath
    ● includedCommands
    ● serverMiddleware
    ● postBuild

    View full-size slide

  18. Addon Build Hooks
    ● treeFor
    ● included
    ● postprocessTree

    View full-size slide

  19. 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`

    View full-size slide

  20. 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`

    View full-size slide

  21. blueprintsPath
    ● No arguments
    ● Return the path for blueprints
    ● Defaults to `blueprints/` (if present)

    View full-size slide

  22. blueprintsPath

    View full-size slide

  23. includedCommands
    ● No arguments
    ● Return an object
    ○ key - command name
    ○ value - command instance or create options
    ● No default implementation.

    View full-size slide

  24. includedCommands

    View full-size slide

  25. serverMiddleware
    ● Receives an “options” argument:
    ○ app -- express instance
    ○ options
    ■ project
    ■ watcher
    ■ environment
    ● No default implementation.

    View full-size slide

  26. serverMiddleware

    View full-size slide

  27. serverMiddleware

    View full-size slide

  28. postBuild
    ● Receives the `result` object from build:
    ○ directory -- path to build output
    ● No default implementation

    View full-size slide

  29. included
    ● Called when the addon is included in a build
    ● Receives the `EmberApp` instance as an arg
    ● Generally used to call `app.import`

    View full-size slide

  30. ● 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

    View full-size slide

  31. 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

    View full-size slide

  32. treeFor
    ● app
    ● styles
    ● templates
    ● addon
    ● vendor
    ● test-support
    ● public

    View full-size slide

  33. treeForApp
    ● Receives tree at `treePaths[‘app’]` (defaults to
    addons `app/` directory)
    ● Return value is merged with the application’s
    app tree.

    View full-size slide

  34. 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/`)

    View full-size slide

  35. 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/`)

    View full-size slide

  36. 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)

    View full-size slide

  37. treeForVendor
    ● Receives tree at `treePaths[‘vendor’]`
    (defaults to addons `vendor/` directory)
    ● Return value is merged with the application’s
    vendor tree (defaults to `vendor/`)

    View full-size slide

  38. 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/`)

    View full-size slide

  39. 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/`

    View full-size slide

  40. 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()`

    View full-size slide

  41. 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

    View full-size slide

  42. Discovery
    ● Search project dependencies
    ○ Look for `ember-addon` in keywords
    ● Search `package.json`’s `ember-addon` key
    for `paths`

    View full-size slide

  43. Discovery - App

    View full-size slide

  44. Discovery - Addon

    View full-size slide

  45. Creating an Addon

    View full-size slide

  46. 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`

    View full-size slide

  47. Creating - External

    View full-size slide

  48. Creating - In Repo

    View full-size slide

  49. Creating - Minimal Addon

    View full-size slide

  50. Testing an Addon

    View full-size slide

  51. Testing
    ● Default generator creates a test app
    ● Unit tests
    ● Integration tests (against test/dummy app)

    View full-size slide

  52. Testing - Unit

    View full-size slide

  53. Testing - Acceptance

    View full-size slide

  54. Testing - Acceptance

    View full-size slide

  55. Dependencies

    View full-size slide

  56. Dependencies
    SHOOT ME NOW!!!

    View full-size slide

  57. 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

    View full-size slide

  58. Dependencies

    View full-size slide

  59. Dependencies

    View full-size slide

  60. Lets see it!

    View full-size slide