@d2js/components v2.2.1

@d2js/components

Module to scan and auto import components for D2 2.17+

Features

• Automatically scan components/ directory
• No need to manually import components anymore
• Multiple paths with customizable prefixes and lookup/ignore patterns
• Lazy loading (Async components)
• Production code-splitting optimization (loader)
• Hot reloading
• Module integration (library authors)
• Fully tested

Usage

Set the components option in d2.config:

export default {
  components: true
}

Create your components:

| components/
---| ComponentFoo.kdu
---| ComponentBar.kdu

Use them whenever you want, they will be auto imported in .kdu files :

<template>
  <ComponentFoo />
  <component-bar />
</template>

No need anymore to manually import them in the script section!

Lazy Imports

D2 by default does code-splitting per page and components. But sometimes we also need to lazy load them:

• Component size is rather big (or has big dependencies imported) like a text-editor
• Component is rendered conditionally with k-if or being in a modal

In order to lazy load a component, all we need to do is to add Lazy prefix to component name.

You now can easily import a component on-demand:

<template>
  <LazyComponentFoo k-if="foo" />
  <button @click="loadFoo">
    Load Foo
  </button>
</template>

<script>
  export default {
    data() {
      return {
        foo: null
      }
    },
    methods: {
      async loadFoo() {
        this.foo = await this.$axios.$get('foo')
      }
    }
  }
</script>

If you want to prefetch or preload the components with Lazy prefix, you can configure it by prefetch/preload options.

Nested Components

If you have components in nested directories:

| components/
---| my/
------| form/
---------| TextArea.kdu

The component name will contain its path:

<MyFormTextArea />

For clarity, it is recommended that component file name matches its name. You can also use MyFormTextArea.kdu as name with same directory structure.

If for any reason different prefix is desired, we can add specific directory with the prefix option: (See directories section)

components: ['~/components/', { path: '~/components/foo/', prefix: 'foo' }]

Overwriting Components

It is possible to have a way to overwrite components using the level option. This is very useful for modules and theme authors.

Considering this structure:

| node_modules/
---| my-theme/
------| components/
---------| Header.kdu
| components/
---| Header.kdu

Then defining in the d2.config:

components: [
  '~/components', // default level is 0
  { path: 'node_modules/my-theme/components', level: 1 }
]

Our components/Header.kdu will overwrite our theme component since the lowest level overwrites.

Directories

By setting components: true, default ~/components directory will be included. However you can customize module behaviour by providing directories to scan:

export default {
  components: [
    '~/components', // shortcut to { path: '~/components' }
    { path: '~/components/awesome/', prefix: 'awesome' }
  ]
}

Each item can be either string or object. String is shortcut to { path }.

Note: Don't worry about ordering or overlapping directories! Components module will take care of it. Each file will be only matched once with longest path.

Directory Properties

path

• Required
• Type: String

Path (absolute or relative) to the directory containing your components.

You can use D2 aliases (~ or @) to refer to directories inside project or directly use a npm package path similar to require.

extensions

• Type: Array<string>
• Default:
  • Extensions supported by D2 builder (builder.supportedExtensions)
  • Default supported extensions ['kdu', 'js'] or ['kdu', 'js', 'ts', 'tsx'] depending on your environment

Example: Support multi-file component structure

If you prefer to split your SFCs into .js, .kdu and .css, you can only enable .kdu files to be scanned:

| components
---| componentC
------| componentC.kdu
------| componentC.js
------| componentC.scss

// d2.config.js
export default {
  components: [{ path: '~/components', extensions: ['kdu'] }]
}

pattern

• Type: string (glob pattern)
• Default: **/*.${extensions.join(',')}

Accept Pattern that will be run against specified path.

ignore

• Type: Array
• Items: string (glob pattern)
• Default: []

Ignore patterns that will be run against specified path.

prefix

• Type: String
• Default: '' (no prefix)

Prefix all matched components.

Example below adds awesome-/Awesome prefix to the name of components in awesome/ directory.

// d2.config.js
export default {
  components: [
    '~/components',
    { path: '~/components/awesome/', prefix: 'awesome' }
  ]
}

components/
  awesome/
    Button.kdu
  Button.kdu

<template>
  <div>
    <AwesomeButton>Click on me 🤘</AwesomeButton>
    <button>Click on me</button>
  </div>
</template>

pathPrefix

• Type: Boolean
• Default: true

Prefix component name by it's path

watch

• Type: Boolean
• Default: true

Watch specified path for changes, including file additions and file deletions.

transpile

• Type: Boolean
• Default: 'auto'

Transpile specified path using build.transpile, by default ('auto') it will set transpile: true if node_modules/ is in path.

level

• Type: Number
• Default: 0

Level are use to define a hint when overwriting the components which have the same name in two different directories, this is useful for theming.

export default {
  components: [
    '~/components', // default level is 0
    { path: 'my-theme/components', level: 1 }
  ]
}

Components having the same name in ~/components will overwrite the one in my-theme/components, learn more in Overwriting Components. The lowest value will overwrite.

prefetch/preload

• Type: Boolean/Number
• Default: false

These properties are used in production to configure how components with Lazy prefix are handled by Wepack via its magic comments, learn more in Wepack's official documentation.

export default {
  components: [{ path: 'my-theme/components', prefetch: true }]
}

yields:

// plugin.js
const componets = {
  MyComponentA: import(/* webpackPrefetch: true */ ...),
  MyComponentB: import(/* webpackPrefetch: true */ ...)
}

isAsync

• Type: Boolean
• Default: false unless component name ends with .async.kdu

This flag indicates, component should be loaded async (with a seperate chunk) regardless of using Lazy prefix or not.

License

MIT