EmberConf 2017 – Confessions of an Ember Addon Author

EmberConf 2017
Confessions of an Ember Addon Author
Confessions
of an Ember
Addon
Author
PRESENTED BY
Lauren Tan
sugarpirate_
poteto
Cinemagraph by /u/orbojunglist

View Slide

EmberConf 2017
Lauren Tan
sugarpirate_
poteto

View Slide

EmberConf 2017

View Slide

EmberConf 2017
What makes an addon good?

View Slide

EmberConf 2017

View Slide

EmberConf 2017
Documentation
Driven
Development

View Slide

EmberConf 2017

View Slide

EmberConf 2017
If it's not documented,
it doesn't exist
YES, IT'S TRUE

View Slide

EmberConf 2017
defmodule KVServer.Command do
@doc ~S"""
Parses the given `line` into a command.
"## Examples
iex> KVServer.Command.parse "CREATE shopping\r\n"
{:ok, {:create, "shopping"}}
"""
def parse(line) do
:not_implemented
end
end

View Slide

EmberConf 2017

View Slide

EmberConf 2017
If you build it, they
will might (not)
come
YOU'VE BEEN LIED TO

View Slide

EmberConf 2017
Any successful
project requires
two things
Nathan Marz, 2014

View Slide

EmberConf 2017
It solves a useful
problem
TWO THINGS

View Slide

EmberConf 2017
People are
convinced your
solution is the best
for their problem
TWO THINGS

View Slide

EmberConf 2017
https://youtu.be/_0T5OSSzxms

View Slide

EmberConf 2017

View Slide

EmberConf 2017
ȗ 

View Slide

EmberConf 2017

View Slide

EmberConf 2017
I. Addon Anatomy
II. One Weird Trick
III. Open Sourcery

View Slide

EmberConf 2017
Addon Structure
Cinemagraph by /u/Hyperoperation

View Slide

EmberConf 2017
Ember Land

View Slide

EmberConf 2017
Node Land

View Slide

EmberConf 2017
addon
├── -private
│ ├── closure-action.js
│ ├── create-multi-array-helper.js
│ └── create-needle-haystack-helper.js
├── helpers
│ ├── append.js
│ ├── ""...
│ └── without.js
├── index.js
└── utils
├── comparison.js
├── get-index.js
├── includes.js
├── is-equal.js
├── is-object.js
└── is-promise.js
Internals

View Slide

EmberConf 2017
export { default, append } from 'ember-composable-helpers/helpers/append';

View Slide

EmberConf 2017
app
└── helpers
├── append.js
├── ""...
└── without.js Merged into
consuming app

View Slide

EmberConf 2017
"ember-addon": {
"configPath": "tests/dummy/config",
"after": [
"ember-changeset"
]
}

View Slide

EmberConf 2017
Internals are not
really private
A WORD OF CAUTION
import isPromise from 'ember-changeset/utils/is-promise';
import ACTION from 'ember-composable-helpers/-private/closure-action';

View Slide

EmberConf 2017

View Slide

EmberConf 2017
export default function validate<%= classifiedModuleName %>("/* options = {} "*/) {
return ("/* key, newValue, oldValue, changes, content "*/) "=> {
return true;
};
}

View Slide

EmberConf 2017
dasherizedPackageName
classifiedPackageName
dasherizedModuleName
classifiedModuleName
camelizedModuleName
https:"//ember-cli.com/api/classes/Blueprint.html

View Slide

EmberConf 2017
config
blueprintsPath
includedCommands
serverMiddleware
testemMiddleware
postBuild
preBuild
outputReady
buildError
included
shouldIncludeChildAddon
setupPreprocessorRegistry
preprocessTree
postprocessTree
lintTree
contentFor
treeFor
Addon
hooks are
powerful
WORKING IN NODE LAND
https://ember-cli.com/api/classes/Addon.html
Cinemagraph by /u/orbojunglist

View Slide

EmberConf 2017

View Slide

EmberConf 2017
I. setupPreprocessorRegistry
II. treeForAddon

View Slide

EmberConf 2017
SETUP PREPROCESSOR REGISTRY
Strip test selectors
from templates
https://ember-cli.com/api/classes/Addon.html#method_setupPreprocessorRegistry

View Slide

EmberConf 2017

Click me
"

View Slide

EmberConf 2017
TREE FOR ADDON
Remove addon
from build
https://ember-cli.com/api/classes/Addon.html#method_treeForAddon

View Slide

EmberConf 2017

View Slide

EmberConf 2017
Remove unused
helpers from build
TREE FOR ADDON

View Slide

EmberConf 2017
treeForAddon: function() {
"// see: https:"//github.com/ember-cli/ember-cli/issues/4463
var tree = this._super.treeForAddon.apply(this, arguments);
return this.filterHelpers(tree, new RegExp('^modules\/' + this.name + '\/helpers\/', 'i'));
},
filterHelpers: function(tree, regex) {
var whitelist = this.whitelist;
var blacklist = this.blacklist;
var _this = this;
"// exit early if no opts defined
if (whitelist.length ""=== 0 "&& blacklist.length ""=== 0) {
return new Funnel(tree);
}
return new Funnel(tree, {
exclude: [function(name) {
return _this.exclusionFilter(name, regex, {
whitelist: whitelist,
blacklist: blacklist
});
}]
});
}

View Slide

EmberConf 2017

View Slide

EmberConf 2017
Augment
ember-cli
INCLUDED COMMANDS

View Slide

EmberConf 2017
includedCommands: function() {
return {
'deploy': require('./lib/deploy'),
'deploy:activate': require('./lib/activate'),
'deploy:list': require('./lib/list')
};
}

View Slide

EmberConf 2017
I. Addon Anatomy
II. One Weird Trick
III. Open Sourcery

View Slide

EmberConf 2017
Cinemagraph by /u/ibru
Developer Experience

View Slide

EmberConf 2017
Tell a story
WRITING GOOD DOCUMENTATION

View Slide

EmberConf 2017
“I used ES6 classes and my startup failed AMA”

View Slide

EmberConf 2017

View Slide

EmberConf 2017
What is the
public API?

View Slide

EmberConf 2017

View Slide

EmberConf 2017
Show, don't
tell

View Slide

EmberConf 2017

View Slide

EmberConf 2017
Cinemagraph by /u/barracuda415
Testing Your Addon

View Slide

EmberConf 2017
module.exports = {
scenarios: [
{
name: 'ember-1.13',
bower: { "/* ""..."*/ },
npm: { "/* ""..."*/ }
},
{
name: 'ember-lts-2.8',
bower: { "/* ""..."*/ },
npm: { "/* ""..."*/ }
},
{
name: 'ember-release',
bower: { "/* ""..."*/ },
npm: { "/* ""..."*/ }
},
{
name: 'ember-beta',
bower: { "/* ""..."*/ },
npm: { "/* ""..."*/ }
},
{
name: 'ember-canary',
bower: { "/* ""..."*/ },
npm: { "/* ""..."*/ }
},
{
name: 'ember-default',
bower: { "/* ""..."*/ },
npm: { "/* ""..."*/ }
}
]
};
Ensure
Compatibility
With Ember-Try

View Slide

EmberConf 2017
env:
- EMBER_TRY_SCENARIO=ember-lts-2.4
- EMBER_TRY_SCENARIO=ember-lts-2.8
- EMBER_TRY_SCENARIO=ember-release
- EMBER_TRY_SCENARIO=ember-beta
- EMBER_TRY_SCENARIO=ember-canary
- EMBER_TRY_SCENARIO=ember-default

View Slide

EmberConf 2017

View Slide

EmberConf 2017
Test With
A Real
Browser
addons:
apt:
sources:
- google-chrome
packages:
- google-chrome-stable
before_install:
# Setup for Chrome
- export DISPLAY=:99.0
- sh -e /etc/init.d/xvfb start
https://github.com/machty/ember-concurrency/blob/master/.travis.yml

View Slide

EmberConf 2017
Configuration

View Slide

EmberConf 2017
File in /app

View Slide

EmberConf 2017
"// app/transitions.js
export default function() {
this.transition(
this.fromRoute('people.index'),
this.toRoute('people.detail'),
this.use('toLeft'),
this.reverse('toRight')
);
};

View Slide

EmberConf 2017
if (owner.factoryFor) {
let maybeConfig = owner.factoryFor('transitions:main');
config = maybeConfig "&& maybeConfig.class;
} else {
config = owner._lookupFactory('transitions:main');
}

View Slide

EmberConf 2017

View Slide

EmberConf 2017
define("my-app/transitions", ["exports"], function (exports) {
"// ""...
});

View Slide

EmberConf 2017
export default {
url: 'http:"//localhost:3000',
timeout: 1000,
isThing: true
}

View Slide

EmberConf 2017
config/environment.js

View Slide

EmberConf 2017
metricsAdapters: [
{
name: 'Mixpanel',
environments: ['development'],
config: {
token: 'abcd1234'
}
},
{
name: 'GoogleAnalytics',
environments: ['production'],
config: {
id: 'UA-XXXXXXXX-X'
}
}
]

View Slide

EmberConf 2017
"// app/initializers/metrics.js
import config from '"../config/environment';
export function initialize() {
const application = arguments[1] "|| arguments[0];
const { metricsAdapters = [] } = config;
const { environment = 'development' } = config;
const options = { metricsAdapters, environment };
application.register('config:metrics', options, { instantiate: false });
application.inject('service:metrics', 'options', 'config:metrics');
}
export default {
name: 'metrics',
initialize
};

View Slide

EmberConf 2017
import Ember from 'ember';
const { Service, get } = Ember;
export default Service.extend({
init() {
this._super(""...arguments);
let { metricsAdapters, environment } = get(this, 'options');
"// do stuff
}
});

View Slide

EmberConf 2017
ember-cli-build.js

View Slide

EmberConf 2017
module.exports = function(defaults) {
var app = new EmberApp(defaults, {
'ember-composable-helpers': {
only: ['inc', 'dec', 'pipe'],
except: ['pipe', 'filter-by']
}
});
}

View Slide

EmberConf 2017
included: function(app) {
this._super.included.apply(this, arguments);
"// see: https:"//github.com/ember-cli/ember-cli/issues/3718
if (typeof app.import ""!== 'function' "&& app.app) {
app = app.app;
}
this.app = app;
this.app.options = this.app.options "|| {};
var config = this.app.options[this.name] "|| {};
this.whitelist = this.generateWhitelist(config);
this.blacklist = this.generateBlacklist(config);
}

View Slide

EmberConf 2017
Extensibility

View Slide

EmberConf 2017
Ember Land

View Slide

EmberConf 2017
"// addon/metrics-adapters/base.js
const { Object: EmberObject } = Ember;
export default EmberObject.extend({
"// base methods
});
Not Managed
By Ember's
Container

View Slide

EmberConf 2017
"// addon/metrics-adapters/google-analytics.js
import BaseAdapter from './base';
export default BaseAdapter.extend({
"// custom code
});

View Slide

EmberConf 2017
/**
* Looks up the adapter from the resolver. Prioritizes the consuming app's
* adapters over the addon's adapters.
*
* @method _lookupAdapter
* @param {String} adapterName
* @private
* @return {Adapter} a local adapter or an adapter from the addon
"*/
_lookupAdapter(adapterName) {
assert('[ember-metrics] Could not find metrics adapter without a name.', adapterName);
const dasherizedAdapterName = dasherize(adapterName);
const availableAdapter = getOwner(this).lookup(`ember-metrics@metrics-adapter:${dasherizedAdapterName}`);
const localAdapter = getOwner(this).lookup(`metrics-adapter:${dasherizedAdapterName}`);
return localAdapter ? localAdapter : availableAdapter;
}

View Slide

EmberConf 2017
/**
* Instantiates an adapter if one is found.
*
* @method _activateAdapter
* @param {Object}
* @private
* @return {Adapter}
"*/
_activateAdapter({ name, config } = {}) {
const Adapter = this._lookupAdapter(name);
assert(`[ember-metrics] Could not find metrics adapter ${name}.`, Adapter);
return Adapter.create({ this, config });
}

View Slide

EmberConf 2017
Not-Ember Land

View Slide

EmberConf 2017
"/* globals requirejs, requireModule "*/
import defaultMessages from 'ember-changeset-validations/utils/messages';
const { A: emberArray, isPresent } = Ember;
const { keys } = Object;
const matchRegex = /validations\/messages$/gi;
let cachedRef = null;
/**
* Find and load messages module on consuming app. Defaults to addon messages.
* To define a custom message map, create `my-app/app/validations/messages.js`
* and export an object.
*
* @param {Object} moduleMap
* @param {Boolean} useCache Pass `false` to ignore cached key
* @return {Object}
"*/
export default function getMessages(moduleMap = requirejs.entries, useCache = true) {
if (useCache "&& isPresent(cachedRef)) {
return cachedRef;
}
let moduleKey = emberArray(keys(moduleMap))
.find((module) "=> isPresent(module.match(matchRegex)));
let messagesModule = isPresent(moduleKey) ? requireModule(moduleKey).default : defaultMessages;
cachedRef = messagesModule;
return messagesModule;
}
Probably
A Hack

View Slide

EmberConf 2017
"/* globals requirejs, requireModule "*/
import defaultMessages from 'ember-changeset-validations/utils/messages';
const { A: emberArray, isPresent } = Ember;
const { keys } = Object;
const matchRegex = /validations\/messages$/gi;
let cachedRef = null;
/**
* Find and load messages module on consuming app. Defaults to addon messages.
* To define a custom message map, create `my-app/app/validations/messages.js`
* and export an object.
*
* @param {Object} moduleMap
* @param {Boolean} useCache Pass `false` to ignore cached key
* @return {Object}
"*/
export default function getMessages(moduleMap = requirejs.entries, useCache = true) {
if (useCache "&& isPresent(cachedRef)) {
return cachedRef;
}
let moduleKey = emberArray(keys(moduleMap))
.find((module) "=> isPresent(module.match(matchRegex)));
let messagesModule = isPresent(moduleKey) ? requireModule(moduleKey).default : defaultMessages;
cachedRef = messagesModule;
return messagesModule;
}
Probably
A Hack
Don't do this

View Slide

EmberConf 2017

View Slide

EmberConf 2017
Child Addons

View Slide

EmberConf 2017

View Slide

EmberConf 2017
{
"name": "my-ember-service-worker-plugin",
"version": "0.0.0",
"keywords": [
"ember-addon",
"ember-service-worker-plugin"
]
}

View Slide

EmberConf 2017
postprocessTree(type, appTree) {
if (type ""!== 'all') {
return appTree;
}
let plugins = this._findPluginsFor(this.project);
"// Add the project itself as a possible plugin, this way user can add custom
"// service-worker code in their app, without needing to build a plugin.
plugins = [this].concat(plugins, this.project);
"// other setup
},
_findPluginsFor(project) {
let addons = project.addons "|| [];
return addonUtils.filterByKeyword(addons, 'ember-service-worker-plugin');
}

View Slide

EmberConf 2017
Ember Internals

View Slide

EmberConf 2017
https://kapeli.com/dash

View Slide

EmberConf 2017

View Slide

EmberConf 2017
I. Addon Anatomy
II. One Weird Trick
III. Open Sourcery

View Slide

EmberConf 2017
Kitten
OPEN SOURCE LEVEL

View Slide

EmberConf 2017
Cat
OPEN SOURCE LEVEL

View Slide

EmberConf 2017
Veteran
OPEN SOURCE LEVEL

View Slide

EmberConf 2017
wycats
OPEN SOURCE LEVEL

View Slide

EmberConf 2017
Relinquish control
KEEPING YOUR ADDON ALIVE

View Slide

EmberConf 2017
The issue backlog
can be
overwhelming
STAYING SANE

View Slide

EmberConf 2017
It's okay to say no
AVOID BURNOUT

View Slide

EmberConf 2017
Please
SEMVER

View Slide

EmberConf 2017

View Slide

EmberConf 2017
I. Addon Anatomy
II. One Weird Trick
III. Open Sourcery

View Slide

EmberConf 2017
Lauren Tan
sugarpirate_
poteto

View Slide

EmberConf 2017
Cinemagraph by /u/fezzo
Thank you
sugarpirate_
poteto

View Slide

EmberConf 2017 – Confessions of an Ember Addon Author

EmberConf 2017 – Confessions of an Ember Addon Author

Lauren Tan

More Decks by Lauren Tan

Other Decks in Programming

Featured

Transcript