Single File Components

Introduction

In many Vue projects, global components will be defined using Vue.component, followed by new Vue({ el: '#container' }) to target a container element in the body of every page.

This can work very well for small to medium-sized projects, where JavaScript is only used to enhance certain views. In more complex projects however, or when your frontend is entirely driven by JavaScript, these disadvantages become apparent:

• Global definitions force unique names for every component
• String templates lack syntax highlighting and require ugly slashes for multiline HTML
• No CSS support means that while HTML and JavaScript are modularized into components, CSS is conspicuously left out
• No build step restricts us to HTML and ES5 JavaScript, rather than preprocessors like Pug (formerly Jade) and Babel

All of these are solved by single-file components with a .vue extension, made possible with build tools such as Webpack or Browserify.

Here’s a simple example of a file we’ll call Hello.vue:

Now we get:

• Complete syntax highlighting
• CommonJS modules
• Component-scoped CSS

As promised, we can also use preprocessors such as Pug, Babel (with ES2015 modules), and Stylus for cleaner and more feature-rich components.

These specific languages are just examples. You could just as easily use Bublé, TypeScript, SCSS, PostCSS - or whatever other preprocessors that help you be productive. If using Webpack with vue-loader, it also has first-class support for CSS Modules.

What About Separation of Concerns?

One important thing to note is that separation of concerns is not equal to separation of file types. In modern UI development, we have found that instead of dividing the codebase into three huge layers that interweaves with one another, it makes much more sense to divide them into loosely-coupled components and compose them. Inside a component, its template, logic and styles are inherently coupled, and collocating them actually makes the component more cohesive and maintainable.

Even if you don’t like the idea of Single-File Components, you can still leverage its hot-reloading and pre-compilation features by separating your JavaScript and CSS into separate files:

<!-- my-component.vue -->
<template>
  <div>This will be pre-compiled</div>
</template>
<script src="./my-component.js"></script>
<style src="./my-component.css"></style>

Getting Started

For Users New to Module Build Systems in JavaScript

With .vue components, we’re entering the realm of advanced JavaScript applications. That means learning to use a few additional tools if you haven’t already:

• Node Package Manager (NPM): Read the Getting Started guide through section 10: Uninstalling global packages.

• Modern JavaScript with ES2015/16: Read through Babel’s Learn ES2015 guide. You don’t have to memorize every feature right now, but keep this page as a reference you can come back to.

After you’ve taken a day to dive into these resources, we recommend checking out the webpack-simple template. Follow the instructions and you should have a Vue project with .vue components, ES2015 and hot-reloading running in no time!

The template uses Webpack, a module bundler that takes a number of “modules” and then bundles them into your final application. To learn more about Webpack itself, this video offers a good intro. Once you get past the basics, you might also want to check out this advanced Webpack course on Egghead.io.

In Webpack, each module can be transformed by a “loader” before being included in the bundle, and Vue offers the vue-loader plugin to take care of translating .vue single-file components. The webpack-simple template has already set up everything for you, but if you’d like to learn more about how .vue components work with Webpack, you can read the docs for vue-loader.

For Advanced Users

Whether you prefer Webpack or Browserify, we have documented templates for both simple and more complex projects. We recommend browsing github.com/vuejs-templates, picking a template that’s right for you, then following the instructions in the README to generate a new project with vue-cli.