Recommended Best Practices for Component Development

best-practices.md

#Recommended Best Practices for Component Development

• Use npm to manage dependencies. Including bower is unnecessary.

• Split gulp/grunt tasks into separate files e.g. ./tasks/myTask.js. Use a separate [gulp/grunt].config.js file for their settings. This encourages reuse and is easier to comprehend than a single large file.

• Name private class properties with a prepended underscore e.g. _myPrivateProperty.

• If a variable refers to a jQuery object, prepend a $ as a hint, e.g. $element.

• Provide a gh-pages page with an approachable example of how to use the component.

• Provide two versions of your compiled library. A standalone myComponent.js and a bundled myComponent.bundle.js containing all other js dependencies. This allows implementers to avoid duplication if using many components with the same dependencies. It also makes it easy to include a single file when appropriate. List the dependencies somewhere in the repository so an implementer knows which files to include in their app, the [gulp/grunt].config.js is a good place to do this.

• Use isomorphic libs wherever appropriate, e.g. https://github.com/asyncly/EventEmitter2 This promotes reuse in server side libs.

• Web Components use custom events for 'data out', copy this pattern rather than using a global pubsub system: http://webcomponents.org/articles/web-components-best-practices/

• Use a window.MyComponents global namespace to reference your component, e.g.

    component = new MyComponents.ExampleComponent({
        element: "#component"
    });

• Pass an options object to your component's constructor including an element property specifying a css selector to the containing DOM element.