@cmorales_/vite-plugin-html-template

@cmorales_/vite-plugin-html-template is a plugin for vite and mainly for 'Vanilla' (without specific framework, like React.js, Vue, Svelte, ...), with which you can define within the <template> tag as a component, then you can use the <x-template> tag (customizable) and also add HTML attributes (class, data-*, style, aria-*)

Installation

1. Install the package from npmjs.

	bun add @cmorales_/vite-plugin-html-template
	# or npm install ... or pnpm add ... or yarn add ...

2. Import and add the plugin to the vite config.

import { defineConfig } from 'vite'
import htmlTemplate from '@cmorales_/vite-plugin-html-template'

export default defineConfig({
	plugins: [/*...plugins */ htmlTemplate({...})],
	//...vite config

})

Usage

1. In your HTML define a <template> element with an unique id.

[!WARNING]

1. The element <template> must have at least and at most 1 element.
2. The attributes should be added to the element within the <template> tag and not to the <template> element itself.

   <!-- You should add attributes to the element within the <template> element -->
	 <template id="unique-id">
		<div class="..." ...other-attributes></div>
	 </template>

2. Use the template with the <x-template> tag.

[!WARNING] You need add the data-template-id attribute to the <x-template> element referencing the same id as the <template> element to be used.

<x-template data-template-id="template-id"  class="..." style="..." ></x-template>

3. Complete and working example

<!-- You can use it multiple times -->
<x-template data-template-id="primary-button-template" class="disabled-button" data-text="Press it"></x-template>
<x-template data-template-id="primary-button-template" data-text="Another button"></x-template>


<!-- You can add attributes to element within template element  -->
<template id="primary-button-template">
		<button class="primary-button" type="button">{text}</button>
</template>

4. The result will be like:

<button class="primary-button disabled-button" type="button">Press it</button>	
<button class="primary-button" type="button">Another button</button>
	
<template id="primary-button-template">
		<button class="primary-button" type="button">{text}</button>
</template>

API

Template placeholders

You can inject dynamic values into your templates using placeholders.

To define a placeholder, use curly braces inside the template:

<template id="card">
  <div class="card">
    <h2>{title}</h2>
    <p>{description}</p>
  </div>
</template>

Then, pass values using data-* attributes in <x-template>:

<x-template 
  data-template-id="card"
  data-title="Hello world"
  data-description="This is a description"
></x-template>

Result

<div class="card">
  <h2>Hello world</h2>
  <p>This is a description</p>
</div>

Attribute merging

Attributes passed to <x-template> are merged into the root element of the template.

<x-template 
  data-template-id="card"
  class="highlight"
  style="color:red;"
></x-template>

Result

<div class="card highlight" style="color:red;">

Children Slot

You can use the special placeholder {children}

<x-template data-template-id="foo">
	<div> <!-- some children --> </div>
</x-template>

<template id="foo">
	<header>{children}</header>
</template>

Result

<header>
	<div> <!-- some children --> </div>
</header>

You can add html from a custom placeholder

<!-- You can use any html element -->
<x-template data-template-id="foo" data-text="Open Web" data-icon="<svg>...</svg>" ></x-template>


<template id="foo">
	<button type="button">
		{icon}
		<span>{text}</span>
	</button>
</template>

Result

<button>
	<svg>...</svg>
	<span>Open Web</span>
</button>

Supported attributes

You can pass any valid HTML attribute:

• class
• style
• data-*
• aria-*
• etc.

[!NOTE]

• Placeholder names must match the data-* attributes without the data- prefix.
• If a placeholder is not provided, it will remain unchanged.

Plugin options

| Option | Type | Description | Default | | ------ | ------ | --------------------------------------------------------------------------- | -------------- | | tag | string | Custom tag name used to render template instances instead of <x-template> | "x-template" |

Contributing

[!NOTE] You need to have installed NodeJS

1. Clone the repository

git clone https://github.com/Cristian-F-M/vite-plugin-html-template.git

2. Install dependencies

npm install
# or bun install or pnpm install or ...

3. Run test while you are coding

npm run test
# or bun run test or pnpm run test or ...

[!NOTE]

1. You can add more test if your new features need it
2. Ensure you pass all test before create a pull request
3. Change the version in package.json file according to the changes (major, minor, patch)

npm version patch # minor or major	
# bun pm version patch # minor or major
# ...

About the Author

Created by Cristian Morales.

• GitHub: Cristian-F-M
• Twitter: @Morales_M20
• Portfolio: cmorales.work

Support

If you find this tool useful, you can support my work!