npm package: @knyt/glazier
Description: A Bun plugin for server-side rendering and static site generation with built-in hydration for web components.
Author: Morris Allison III
Latest version: 0.4.0

<div align="center">

[![Knyt](./docs/banner.svg)](https://knyt.dev/s/glazier)

🧊 A [Bun](https://bun.sh/) plugin for server-side rendering and static site generation <br /> with built-in hydration for web components.

<small>

This package is part of [Knyt](https://knyt.dev/), a toolkit designed to simplify modern web development.

</small>

[![npm](https://img.shields.io/npm/v/@knyt/glazier?style=flat-square&labelColor=444)](https://www.npmjs.com/package/@knyt/glazier)
[![GitHub](https://img.shields.io/badge/Source_Code-black?style=flat-square&label=GitHub&labelColor=444)](https://github.com/sables-app/knyt/tree/main/packages/glazier)
[![License](https://img.shields.io/badge/License-BSD_3_Clause-blue?style=flat-square&labelColor=444)](https://github.com/sables-app/knyt/blob/main/LICENSE)
<br />
[![Built with Typescript](https://img.shields.io/badge/Built%20with-Typescript-3178c6.svg?style=flat-square&logo=typescript&labelColor=444)](https://www.typescriptlang.org/)
[![Runs on Bun ^1.2.21](https://img.shields.io/badge/Runs%20on-Bun_^1.2.21-b49090.svg?style=flat-square&logo=bun&labelColor=444)](https://bun.sh/)

</div>

## Key benefits

- **Write HTML, not templates** – Compose pages with standard HTML, no custom syntax
- **Built for Bun’s ecosystem** – Leverages native tooling and module resolution
- **Your rendering, your rules** – Mix SSG, SSR, and hydration with ease
- **Web Components, zero config** – Auto-detects components, renders open/closed shadow roots, requiring no wrapper logic \*
- **Extensible content support** – Built-in recognition for MDX, frontmatter, and table of contents \*\*
- **Extend without friction** – Middleware and plugin system for custom logic

<small>

\* _Closed shadow roots are rendered by implementing a simple interface, without exposing the shadow root._ <br />
\*\* _Add MDX features by installing plugins – the integration points are built in._

</small>

## Try in GitHub Codespaces

You can try Knyt Glazier in your browser using [GitHub Codespaces][]. The pre-configured devcontainers can be used to explore Knyt's server-side capabilities without needing to set up a local environment.

[GitHub Codespaces]: https://github.com/features/codespaces

[![Edit in GitHub Codespaces](./docs/edit-in-codespaces.svg)](https://knyt.dev/try/codespaces)

## Key Features

#### HTML composition

- Composition using standard HTML tags - no custom templating syntax required
- Slot-based content interpolation for flexible layouts
- Native support for including and rendering [Web Components][]/[Views][]
- `Request`-driven architecture for dynamic data injection

[Web Components]: https://developer.mozilla.org/en-US/docs/Web/API/Web_components
[Views]: https://knyt.dev/guide/views

#### SSG & SSR

- Full static site generation for component-based HTML pages
- Complete server-side rendering for dynamic pages
- Partial HTML snippet rendering ([htmx][]-compatible)
- Web Component hydration via Knyt [Luthier][]
- Extensible through middleware with utilities for request data association/overrides

[htmx]: https://htmx.org
[Luthier]: https://knyt.dev/s/luthier

#### Batteries-included

- Built-in MDX and Web Component recognition
- Automatic frontmatter and table-of-contents extraction from MDX
- Optional file-based routing (document path to route conversion)
- Route-aware asset handling via Bun's static bundler
- [Knyt Live Mode][] for development with hot reloading

[Knyt Live Mode]: https://knyt.dev/guide/live-mode

#### Dependency management

- Automatic dependency resolution, bundling and injection
- Progressive, non-blocking hydration strategy
- Memory-efficient virtual module system (no filesystem clutter)
- Seamless Bun integration: Leverages Bun's native toolchain and module system

## Documentation

Documentation is available at [knyt.dev](https://knyt.dev), including guides for:

- [Server-side-includes](https://knyt.dev/guide/server-side-includes)
- [Server-side-rendering](https://knyt.dev/guide/server-side-rendering)
- [Static-site-generation](https://knyt.dev/guide/static-site-generation)

## Usage

To include an HTML snippet you can use the `<knyt-include>` tag:

```html
<!doctype html>
<html lang="en">
  <head>
    <title>My Page</title>
  </head>
  <body>
    <!-- Include an HTML snippet -->
    <knyt-include src="./body-content.html"></knyt-include>
  </body>
</html>
```

Then, run the Bun server:

```bash
NODE_ENV=production bun index.html
```

## Install

First, ensure you have [Bun](https://bun.sh/) installed (v1.2.21 or later).

Then, install the package using Bun:

```sh
bun add @knyt/glazier
```

Then, add the plugin to your `bunfig.toml` file:

```toml [bunfig.toml]
preload = ["@knyt/glazier/preload"]

[serve.static]
plugins = ["@knyt/glazier/plugin"]
```

Now you can use the plugin in your HTML files.

## Updates

See the [CHANGELOG](./CHANGELOG.md) for a list of changes.

## License

This package is licensed under the [BSD 3-Clause License](./LICENSE).

## Open-Source Initiative

This project is supported by [Sables Applications LLC](https://sables.app) as part of its open-source initiatives.