npm - @devsantara/head - Versions diffs - 0.2.0 - Mend

@devsantara/head 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/LICENSE +21 -0
package/README.md +330 -0
package/dist/adapters/index.d.ts +39 -0
package/dist/adapters/index.js +72 -0
package/dist/index.d.ts +293 -0
package/dist/index.js +484 -0
package/dist/types-Cvpk_Zha.d.ts +455 -0
package/package.json +62 -0

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 Devsantara
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,330 @@
+# @devsantara/head
+**A lightweight, type-safe HTML `<head>` builder for modern web applications.**
+Build SEO-friendly metadata with a fluent API, full TypeScript support, and framework adapters for **React**, **TanStack Router/Start**, and more.
+---
+> [!WARNING]
+> **Early Development**: This library is in active development (v0.x.x). Expect breaking changes between minor versions until v1.0. We recommend pinning to exact versions in production.
+## ✨ Features
+### Developer Experience First
+- **Fluent Builder API** – Chain methods naturally for readable, maintainable metadata configuration
+- **Full TypeScript Support** – Autocomplete, type checking, and inline documentation in your IDE
+- **Zero Dependencies** – Lightweight core with optional framework adapters
+### Comprehensive Head Management
+- **SEO Essentials** – Title, description, canonical URLs, robots directives.
+- **Social Media** – Open Graph and Twitter Card meta tags for rich previews.
+- **Mobile Optimization** – Viewport configuration, color schemes, PWA icons.
+- **Advanced Tags** – Alternates, manifests, stylesheets, scripts, and custom meta tags.
+- **Simplified URL Management** – Most metadata (Open Graph, canonical, alternates) requires absolute URLs. Set `metadataBase` once and use convenient relative paths everywhere.
+- **Continuously Expanding** – Actively adding more metadata types based on community feedback.
+### Framework Integration
+- **React Adapter** – Generate React components directly from your metadata
+- **TanStack Router** – First-class support for route-level metadata
+- **Framework Agnostic** – Works with vanilla JS, SSR, SSG, or any rendering strategy
+## 📦 Installation
+```bash
+# npm
+npm install @devsantara/head
+# pnpm
+pnpm add @devsantara/head
+# yarn
+yarn add @devsantara/head
+# bun
+bun add @devsantara/head
+```
+> **Note:** Framework adapters are included in the core package. No additional installations needed.
+## 🚀 Quick Start
+### Basic Usage
+```typescript
+import { HeadBuilder } from '@devsantara/head';
+const head = new HeadBuilder()
+  .addTitle('My Awesome Website')
+  .addDescription('A comprehensive guide to web development')
+  .addViewport({ width: 'device-width', initialScale: 1 })
+  .build();
+```
+```typescript
+// Output (HeadElement[]):
+[
+  {
+    type: 'title',
+    attributes: { children: 'My Awesome Website' },
+  },
+  {
+    type: 'meta',
+    attributes: {
+      name: 'description',
+      content: 'A comprehensive guide to web development',
+    },
+  },
+  {
+    type: 'meta',
+    attributes: {
+      name: 'viewport',
+      content: 'width=device-width, initial-scale=1',
+    },
+  },
+];
+```
+### With Metadata Base URL
+Use `metadataBase` to automatically resolve relative URLs to absolute URLs:
+```typescript
+import { HeadBuilder } from '@devsantara/head';
+const head = new HeadBuilder({
+  metadataBase: new URL('https://devsantara.com'), // <- Add metadata base URL
+})
+  .addTitle('My Blog Post')
+  .addOpenGraph((helper) => ({
+    title: 'My Blog Post',
+    url: helper.resolveUrl('/blog/my-post'),
+    image: {
+      url: helper.resolveUrl('/images/og-image.jpg'),
+    },
+  }))
+  .build();
+```
+```typescript
+// Output (HeadElement[]):
+[
+  {
+    type: 'title',
+    attributes: { children: 'My Blog Post' },
+  },
+  {
+    type: 'meta',
+    attributes: {
+      property: 'og:title',
+      content: 'My Blog Post',
+    },
+  },
+  {
+    type: 'meta',
+    attributes: {
+      property: 'og:url',
+      content: 'https://devsantara.com/blog/my-post',
+    },
+  },
+  {
+    type: 'meta',
+    attributes: {
+      property: 'og:image',
+      content: 'https://devsantara.com/images/og-image.jpg',
+    },
+  },
+];
+```
+### With React Adapter
+```tsx
+import { HeadBuilder } from '@devsantara/head';
+import { HeadReactAdapter } from '@devsantara/head/adapters';
+const head = new HeadBuilder({
+  adapter: new HeadReactAdapter(), // <- Add React adapter
+})
+  .addTitle('My Awesome Website')
+  .addDescription('A comprehensive guide to web development')
+  .build();
+// Use in your document
+export function Document() {
+  return (
+    <html>
+      <head>{head}</head>
+      {/* ... */}
+    </html>
+  );
+}
+```
+```typescript
+// Output (React.ReactNode[]):
+[
+  <title>My Awesome Website</title>,
+  <meta
+    name="description"
+    content="A comprehensive guide to web development"
+  />,
+];
+```
+### With TanStack Router/Start Adapter
+```tsx
+import { HeadBuilder } from '@devsantara/head';
+import { HeadTanstackRouterAdapter } from '@devsantara/head/adapters';
+import { createRootRoute } from '@tanstack/react-router';
+export const Route = createRootRoute({
+  head: () => {
+    return new HeadBuilder({
+      adapter: new HeadTanstackRouterAdapter(), // <- Add Tanstack router adapter
+    })
+      .addTitle('About Us')
+      .addDescription('Learn more about our company')
+      .build();
+  },
+});
+```
+```typescript
+// Output (Tanstack Router Head[]):
+[
+  meta: [
+    { title: 'About Us' },
+    {
+      name: 'description',
+      content: 'Learn more about our company',
+    },
+  ],
+  links:[],
+  scripts:[],
+  styles: []
+]
+```
+## 📚 API Reference
+### Core Methods
+| Method    | Description                                                    |
+| --------- | -------------------------------------------------------------- |
+| `build()` | Builds and returns the final head elements (or adapted output) |
+### Basic Elements
+For advanced use cases not covered by the essential methods below, use these basic methods to add any custom element directly.
+| Method                                                  | Description                                      |
+| ------------------------------------------------------- | ------------------------------------------------ |
+| `addTitle(title: string)`                               | Adds a `<title>` element                         |
+| `addMeta(attributes: HeadAttributeTypeMap['meta'])`     | Adds a `<meta>` element with custom attributes   |
+| `addLink(attributes: HeadAttributeTypeMap['link'])`     | Adds a `<link>` element with custom attributes   |
+| `addScript(attributes: HeadAttributeTypeMap['script'])` | Adds a `<script>` element with custom attributes |
+| `addStyle(attributes: HeadAttributeTypeMap['style'])`   | Adds a `<style>` element with custom attributes  |
+### Essential Methods
+High-level convenience methods for common metadata patterns. These methods handle the complexity of creating properly structured head.
+| Method                                                                 | Description                                                 |
+| ---------------------------------------------------------------------- | ----------------------------------------------------------- |
+| `addDescription(description: string)`                                  | Adds a meta description tag                                 |
+| `addCanonical(valueOrFn: BuilderOption<string \| URL>)`                | Adds a canonical URL link                                   |
+| `addRobots(options: RobotsOptions)`                                    | Adds robots meta tag for search engine directives           |
+| `addCharSet(charset: CharSet)`                                         | Adds character encoding declaration                         |
+| `addViewport(options: ViewportOptions)`                                | Adds viewport configuration for responsive design           |
+| `addColorScheme(colorScheme: ColorScheme)`                             | Adds color scheme preference (light/dark mode)              |
+| `addOpenGraph(valueOrFn: BuilderOption<OpenGraphOptions>)`             | Adds Open Graph meta tags for social media previews         |
+| `addTwitter(valueOrFn: BuilderOption<TwitterOptions>)`                 | Adds Twitter Card meta tags                                 |
+| `addIcon(preset: IconPreset, valueOrFn: BuilderOption<IconOptions>)`   | Adds favicon or app icons (favicon, apple-touch-icon, etc.) |
+| `addStylesheet(href: string \| URL, options?: StylesheetOptions)`      | Adds an external stylesheet link                            |
+| `addManifest(valueOrFn: BuilderOption<string \| URL>)`                 | Adds a web app manifest link                                |
+| `addAlternateLocale(valueOrFn: BuilderOption<AlternateLocaleOptions>)` | Adds alternate language/locale links                        |
+> **💡 Tip:** Most methods support either direct values or callback functions that receive a helper object with `resolveUrl()` for dynamic URL resolution.
+## 🔌 Adapters
+Adapters transform the raw `HeadElement[]` output into framework-specific formats. The library includes built-in adapters for popular frameworks, and you can create custom adapters for your specific needs.
+### Built-in Adapters
+| Framework             | Adapter                     | Output Type                   |
+| --------------------- | --------------------------- | ----------------------------- |
+| React                 | `HeadReactAdapter`          | `React.ReactNode[]`           |
+| Tanstack Router/Start | `HeadTanstackRouterAdapter` | TanStack Router `Head` object |
+### Creating Custom Adapters
+You can create your own adapter by implementing the `HeadAdapter<T>` interface:
+```typescript
+import type { HeadAdapter, HeadElement } from '@devsantara/head';
+// Create a custom adapter that outputs HTML strings
+class HeadHTMLAdapter implements HeadAdapter<string> {
+  transform(elements: HeadElement[]): string {
+    return elements
+      .map((element) => {
+        const { type, attributes } = element;
+        const attrs = Object.entries(attributes)
+          .filter(([key]) => key !== 'children')
+          .map(([key, value]) => `${key}="${value}"`)
+          .join(' ');
+        const children = attributes.children || '';
+        if (type === 'meta' || type === 'link') {
+          return `<${type} ${attrs}>`;
+        }
+        return `<${type} ${attrs}>${children}</${type}>`;
+      })
+      .join('\n');
+  }
+}
+```
+```typescript
+// Use your custom adapter
+const html = new HeadBuilder({
+  adapter: new HeadHTMLAdapter(), // <- Add custom HTML adapter
+})
+  .addTitle('My Site')
+  .addDescription('My description')
+  .build();
+```
+```html
+<!-- Output (HTML string) -->
+<title>My Site</title>
+<meta name="description" content="My description" />
+```
+### Adapter Interface
+```typescript
+interface HeadAdapter<T> {
+  transform(elements: HeadElement[]): T;
+}
+```
+**Parameters:**
+- `elements` - Array of head elements with `type` and `attributes`
+**Returns:**
+- `T` - Your custom output format (string, object, framework components, etc.)
+## 📄 License
+Licensed under the [MIT license](./LICENSE).

package/dist/adapters/index.d.ts ADDED Viewed

@@ -0,0 +1,39 @@
+import { c as HeadMetaAttributes, i as HeadAdapter, l as HeadScriptAttributes, o as HeadElement, s as HeadLinkAttributes, u as HeadStyleAttributes } from "../types-Cvpk_Zha.js";
+import { ReactNode } from "react";
+//#region src/adapters/react-adapter.d.ts
+type HeadReactAdapterResult = ReactNode[];
+/**
+ * Adapter that transforms head elements into React components for rendering in React applications.
+ */
+declare class HeadReactAdapter implements HeadAdapter<HeadReactAdapterResult> {
+  /**
+   * Transforms head elements into React components.
+   *
+   * @param elements - Array of head elements to transform
+   * @returns Array of React components ready for rendering
+   */
+  transform(elements: HeadElement[]): HeadReactAdapterResult;
+}
+//#endregion
+//#region src/adapters/tanstack-router-adapter.d.ts
+interface HeadTanStackRouterAdapterResult {
+  links?: HeadLinkAttributes[];
+  scripts?: HeadScriptAttributes[];
+  meta?: HeadMetaAttributes[];
+  styles?: HeadStyleAttributes[];
+}
+/**
+ * Adapter that transforms head elements into TanStack Router head configuration format.
+ */
+declare class HeadTanstackRouterAdapter implements HeadAdapter<HeadTanStackRouterAdapterResult> {
+  /**
+   * Transforms head elements into TanStack Router head configuration with elements organized by type.
+   *
+   * @param elements - Array of head elements to transform
+   * @returns Head configuration object with categorized elements
+   */
+  transform(elements: HeadElement[]): HeadTanStackRouterAdapterResult;
+}
+//#endregion
+export { HeadReactAdapter, HeadReactAdapterResult, HeadTanStackRouterAdapterResult, HeadTanstackRouterAdapter };

package/dist/adapters/index.js ADDED Viewed

@@ -0,0 +1,72 @@
+import { createElement } from "react";
+//#region src/adapters/react-adapter.ts
+/**
+* Adapter that transforms head elements into React components for rendering in React applications.
+*/
+var HeadReactAdapter = class {
+	/**
+	* Transforms head elements into React components.
+	*
+	* @param elements - Array of head elements to transform
+	* @returns Array of React components ready for rendering
+	*/
+	transform(elements) {
+		return elements.map((element, index) => {
+			const { type, attributes } = element;
+			return createElement(type, {
+				key: `head-${type}-${index}`,
+				...attributes
+			});
+		});
+	}
+};
+//#endregion
+//#region src/utils.ts
+/**
+* Type guard that checks if a head element matches a specific element type.
+*
+* @param element - The head element to check
+* @param type - The expected element type
+* @returns True if the element matches the specified type
+*/
+function isElementOfType(element, type) {
+	return element.type === type;
+}
+//#endregion
+//#region src/adapters/tanstack-router-adapter.ts
+/**
+* Adapter that transforms head elements into TanStack Router head configuration format.
+*/
+var HeadTanstackRouterAdapter = class {
+	/**
+	* Transforms head elements into TanStack Router head configuration with elements organized by type.
+	*
+	* @param elements - Array of head elements to transform
+	* @returns Head configuration object with categorized elements
+	*/
+	transform(elements) {
+		const config = {
+			meta: [],
+			links: [],
+			scripts: [],
+			styles: []
+		};
+		for (const element of elements) if (isElementOfType(element, "meta")) config.meta?.push(element.attributes);
+		else if (isElementOfType(element, "link")) config.links?.push(element.attributes);
+		else if (isElementOfType(element, "script")) config.scripts?.push(element.attributes);
+		else if (isElementOfType(element, "style")) config.styles?.push(element.attributes);
+		else if (isElementOfType(element, "title"))
+ /**
+		* TanStack Router automatically dedupes title and meta tags
+		* so we only need to push the title as a meta element
+		*/
+		config.meta?.push({ title: String(element.attributes.children) });
+		return config;
+	}
+};
+//#endregion
+export { HeadReactAdapter, HeadTanstackRouterAdapter };