Vite-plugin-html-components NPM

vite-plugin-html-components

Vite plugin for breaking down HTML and CSS into components.

Installation

npm i vite-plugin-html-components -D

// vite.config.ts

import { defineConfig } from 'vite'
import { vitePluginHTMLComponents } from 'vite-plugin-html-components'

export default defineConfig({
  plugins: [vitePluginHTMLComponents()],
})

Pages

All website pages should be located inside the src directory and specified in the plugin options:

src
  index.html
  about.html
  contacts
    index.html

export default defineConfig({
  plugins: [
    vitePluginHTMLComponents({
      pages: ['index.html', 'about.html', 'contacts/index.html'],
    }),
  ],
})

Components

Using this plugin, a component is considered a folder inside the src/components/ directory. Embedding a component on a page or within another component is done using the <component> tag:

<body>
  <component:header></component:header>
  <h1>HOME</h1>
  <component:footer />
</body>

The tag can be either paired or single. After the ":" symbol, specify the component name as it is named in the src/components/ directory.

Components can be deeply nested:

src
  components
    my-component
      nested-folder
        another-folder
          component

Access will look like this:

<component:my-component:nested-folder:another-folder:component />

In general, consider any folder inside src/components/ as a component, and you can add it to the page using this tag.

When adding a component, the plugin checks if there are index.html, index.css, index.js/ts files inside, and if any of these files exist, it will be added to the page.

Component Isolation

Each component can be isolated and developed separately by navigating to its address. Here is the structure:

src
  components
    a
      b
        c

will be available at these links:

http://localhost:5173/components/a/ http://localhost:5173/components/a/b/ http://localhost:5173/components/a/b/c/

The deepest nested component will include all index.js/ts and index.css files starting from the root component on the page.

Layout

Inside src/components/, you can create a special folder named layout. All components, when viewed in isolation, will use it as a template.

Nesting

Functionality similar to slots in Vue or Web-components that allows inserting content at a specific location.

<!-- src/components/a -->
<div>
  <div>
    <nest>Unnamed nest default value</nest>
  </div>
  <div>
    <nest name="named-nest">Named nest default value</nest>
  </div>
</div>

<!-- src/components/b -->
<component:a>
  <div>1</div>
  <div nest="named-nest">2</div>
</component:a>

Passing Attributes

<!-- src/components/a -->
<div data-theme="{{ theme }}">{{ value | default value }}</div>

<!-- src/components/b -->
<component:a
  value="hi"
  theme="red"
/>

If the attribute is not passed and does not have a default value, it still remains on the page; you can remove it by specifying the default value as "-":

<div data-theme="{{ theme | - }}"></div>

Plugin Options

export default defineConfig({
  plugins: [
    vitePluginHTMLComponents({
      pages: ['index.html', 'about.html', 'contacts/index.html'],
      splitAssets: false,
    }),
  ],
})

pages

In pages, specify the pages as they are located in the src directory. All specified pages here will be included in the build.

splitAssets

By default, the value is false, and all JS and CSS files are compiled into one file. If set to true, all JS and CSS files will be structured the same way as in src/components.

In some cases, when using this option, the order of assets in the <head> after the build might be incorrect. I'm not precisely aware of how Vite organizes files, but it heavily depends on whether the component has a JS file. If you believe that something should come first, but after the build, it doesn't, try adding an empty index.js/ts file to the component.

Notes

Make sure that your pages or layouts contain the <head></head> tag; it is necessary for inserting assets.

vite-plugin components html split code split parts static

3 months ago

3 months ago

3 months ago

3 months ago