Simple Guide to Authoring Open-Source Vue.js Components

1. Expose the transpiled es5 .js file

Make sure your package.json file leads to the transpiled file instead of the .vue source component. This will make it accessible for everyone. Sure, there is Babel and many developers use it on a daily basis, but there are some that don’t. This will also eliminate the need of having to use webpack’s vue-loader or vueify transform for browserify, as your component will be just plain, good ol’ javascript code.

2. Wrap the .js file as an UMD module.

This will ensure it works with RequireJS, AMD, and CommonJS, thus solving most problems with importing the component. You will even be able to link your components with simple <script> tags, as they will be treated as independent assets. With Webpack you can simply output your component’s bundle as UMD module with this config:

output: {
  library: 'ComponentName',
  libraryTarget: 'umd'
}

Obviously, you will still be able to use es6 module imports!

3. Don’t use the scoped param for styles.

Even though it is extremely useful while writing components for your app, it will make the styles much harder to override and, therefore, harder to customise your component. Save your users from writing unnecessary, too !important, high specificity rules. To prevent leaking of your styles just use a unique CSS class prefix like .component-name__element for every element. I personally follow the BEM methodology and try to keep my styles flat (no nesting).

Remember: Never style basic tags if you’re not scoping the styles!

4. Expose your component logic inside mixins.

This will make it possible to create similar, more specific components based on your component’s functionality. Your solution doesn’t have to cover all the possible use cases. Just make it elastic enough to make it extendable! This can further lead to new, custom versions of your component.

5. Remember about the public API guidelines

Those can be found in the official Vue.js guide.

Here's an example from the docs.

<my-component
  :foo="baz"
  :bar="qux"
  @event-a="doThis"
  @event-b="doThat">
  <!-- content -->
  <img slot="icon" src="...">
  <p slot="main-text">Hello!</p>
</my-component>

6. Test your code!

This one is pretty obvious. Make sure you have solid test coverage so that whenever you fix bugs, do some refactoring or introduce new features, you will always know if everything works properly. This will also prove extremely useful for code contributed by others.

Additionally, high code coverage makes your library more trustworthy and might encourage other developers to use it.

7. Keep the functionality in check.

Though it might be tempting to solve every feature request, this might lead to an overcomplicated and inflexible solution. It’s better to have a strict idea of what your component should solve and what it should not. Do not make assumptions about things like validation or how the data will be handled outside of your component, because those will most likely be proved wrong.

8. Forget about parent-child two-way binding

Most Vue.js apps are probably using some kind of state management solution. For example Vuex will force the developer to not mutate the state outside of the store’s mutations. If you really need to allow two-way binding between the parent and your component, make it an opt-in/opt-out option. The .sync modifier will be deprecated in Vue 2.0 anyway. However, because javascript passes objects as a reference to an existing object, one-way binding must be done explicitly in such cases. If you need to update the prop, just emit an event.

9. Keep in mind that Vue.js 2.0 is already around the corner.

If you’re just starting, it might be a good idea to mind the upcoming 2.0 changes so you don’t have to rewrite your code later.

Oh, and if you consider Vue.js in your next project, my colleagues and I crafted the State of Vue.js report which will definitely help you make an educated decision.