# Kdu Single-File Component (SFC) Spec

# Intro

A *.kdu file is a custom file format that uses HTML-like syntax to describe a Kdu component. Each *.kdu file consists of three types of top-level language blocks: <template>, <script>, and <style>, and optionally additional custom blocks:

<template>
  <div class="example">{{ msg }}</div>
</template>

<script>
export default {
  data () {
    return {
      msg: 'Hello world!'
    }
  }
}
</script>

<style>
.example {
  color: red;
}
</style>

<custom1>
  This could be e.g. documentation for the component.
</custom1>

kdu-loader will parse the file, extract each language block, pipe them through other loaders if necessary, and finally assemble them back into an ES Module whose default export is a Kdu.js component options object.

kdu-loader supports using non-default languages, such as CSS pre-processors and compile-to-HTML template languages, by specifying the lang attribute for a language block. For example, you can use Sass for the style of your component like this:

<style lang="sass">
  /* write Sass! */
</style>

More details can be found in Using Pre-Processors.

# Language Blocks

# Template

Each *.kdu file can contain at most one <template> block at a time.
Contents will be extracted and passed on to kdu-template-compiler and pre-compiled into JavaScript render functions, and finally injected into the exported component in the <script> section.

# Script

Each *.kdu file can contain at most one <script> block at a time.
The script is executed as an ES Module.
The default export should be a Kdu.js component options object (opens new window). Exporting an extended constructor created by Kdu.extend() is also supported, but a plain object is preferred.
Any webpack rules that match against .js files (or the extension specified by the lang attribute) will be applied to contents in the <script> block as well.

# Style

Default match: /\.css$/.
A single *.kdu file can contain multiple <style> tags.
A <style> tag can have scoped or module attributes (see Scoped CSS and CSS Modules) to help encapsulate the styles to the current component. Multiple <style> tags with different encapsulation modes can be mixed in the same component.
Any webpack rules that match against .css files (or the extension specified by the lang attribute) will be applied to contents in the <style> blocks as well.

# Custom Blocks

Additional custom blocks can be included in a *.kdu file for any project specific needs, for example a <docs> block. kdu-loader will use the tag name to look up which webpack loaders should be applied to the contents of the section. The webpack loaders should be specified in the loaders section of kdu-loader options.

For more details, see Custom Blocks.

# Src Imports

If you prefer splitting up your *.kdu components into multiple files, you can use the src attribute to import an external file for a language block:

<template src="./template.html"></template>
<style src="./style.css"></style>
<script src="./script.js"></script>

Beware that src imports follow the same path resolution rules to webpack module requests, which means:

Relative paths need to start with ./
You can import resources from npm dependencies:

<!-- import a file from the installed "todomvc-app-css" npm package -->
<style src="todomvc-app-css/index.css">

src imports also work with custom blocks, e.g.:

<unit-test src="./unit-test.js">
</unit-test>

# Syntax Highlighting / IDE Support

Currently there is syntax highlighting support for the following IDE/editors:

VS Code (opens new window)

Contributions for other editors/IDEs are highly appreciated! If you are not using any pre-processors in Kdu components, you can also get decent syntax highlighting by treating *.kdu files as HTML in your editor.

# Comments

Inside each block you shall use the comment syntax of the language being used (HTML, CSS, JavaScript, Jade, etc). For top-level comments, use HTML comment syntax: 