npm package: @raven-js/beak
Description: Zero-dependency templating library for modern JavaScript - HTML, CSS, SQL, Markdown and more
Author: Anonyfox
Latest version: 0.4.48

# Beak

[![Website](https://img.shields.io/badge/ravenjs.dev-000000?style=flat&logo=firefox&logoColor=white)](https://ravenjs.dev)
[![Documentation](https://img.shields.io/badge/docs-ravenjs.dev%2Fbeak-blue.svg)](https://docs.ravenjs.dev/beak)
[![Zero Dependencies](https://img.shields.io/badge/Zero-Dependencies-brightgreen.svg)](https://github.com/Anonyfox/ravenjs)
[![ESM Only](https://img.shields.io/badge/ESM-Only-purple.svg)](https://nodejs.org/api/esm.html)
[![Node.js 22.5+](https://img.shields.io/badge/Node.js-22.5+-green.svg)](https://nodejs.org/)

<div align="center">
  <img src="./media/logo.webp" alt="Beak Logo" width="200" height="200" />
</div>

**Zero-dependency template engine for modern JavaScript.** Tagged template literals for HTML, CSS, SQL, XML, and Markdown with progressive SEO generators and platform-native performance.

## Purpose

Template engines add build complexity, runtime overhead, and vendor lock-in to solve problems that JavaScript template literals already handle efficiently. Most engines compile templates into string concatenation—exactly what template literals provide natively.

Beak eliminates the middleman. Write templates using native JavaScript syntax, get V8-optimized performance, and deploy anywhere without transpilation. Zero external dependencies prevent supply chain attacks and breaking changes from abandoned maintainers.

When your templates are JavaScript, they evolve with the platform instead of waiting for tool updates.

## Installation

```bash
npm install @raven-js/beak
```

## Usage

Import template functions and use them as tagged template literals:

```javascript
import {
  html, css, md, sh, sql,
  openGraph, canonical, feed, sitemap
} from "@raven-js/beak";

// Core HTML generation with progressive features
const page = html`
  <div class="${isActive ? "active" : "inactive"}">
    <h1>${title}</h1>
    ${items.map((item) => html`<li>${item.name}</li>`)}
  </div>
`;

// CSS with object-to-kebab-case conversion
const styles = css`
  .card {
    ${{ fontSize: "16px", borderRadius: [4, 8] }}px;
    color: ${theme.primary};
  }
`;

// SQL with injection prevention
const query = sql`
  SELECT * FROM users
  WHERE name = '${userName}' AND status = '${status}'
`;

// Markdown with context-aware composition
const content = md`
  # ${title}

  ${description}

  ## Features

  ${features.map(f => `- ${f}`).join('\n')}
`;

// Progressive SEO generators
const meta = html`
  ${canonical({ domain: 'example.com', path: '/article' })}
  ${openGraph({ title, description, image: '/hero.jpg' })}
`;

// XML feeds and sitemaps
const rssFeed = feed({
  title: 'Blog Posts',
  description: 'Latest articles',
  link: 'https://blog.example.com',
  items: posts
});

const xmlSitemap = sitemap({
  domain: 'example.com',
  pages: posts.map(p => ({ path: p.slug, priority: 0.8 }))
});
```

## Content-As-Code

Everything becomes programmable JavaScript => no separate build pipelines, no multiple file types, no synchronization headaches.

**Traditional:** `styles.css` + `template.html` + `component.js` = coordination nightmare
**Beak:** Single JavaScript file with all content as template literals = unified tooling

**Security options for untrusted content:**

```javascript
// Automatic XSS protection
const safe = safeHtml`<p>User: ${userInput}</p>`;

// Manual escaping when needed
const escaped = escapeHtml('<script>alert("xss")</script>');
```

**Tree-shaking with sub-imports:**

```javascript
// Import only what you need
import { html, safeHtml } from "@raven-js/beak/html";
import { openGraph, canonical, author, robots, twitter } from "@raven-js/beak/html";
import { xml, feed, sitemap } from "@raven-js/beak/xml";
import { md, markdownToHTML } from "@raven-js/beak/md";
```

## IDE Integration

VS Code and Cursor plugin provides syntax highlighting and IntelliSense for all template types:

```bash
TODO: not yet published, see the plugins/vscode folder to get it
```

Zero configuration required. Templates get full IDE support with automatic completion and error detection.

## SEO Integration

Progressive generators that scale from basic meta tags to enterprise content ecosystems:

```javascript
import { openGraph, canonical, author, robots, twitter } from "@raven-js/beak/html";
import { feed, sitemap } from "@raven-js/beak/xml";

// Basic social sharing
const basicMeta = openGraph({
  title: "Article Title",
  description: "Article description",
  image: "/hero.jpg"
});

// Advanced content specialization
const advancedMeta = html`
  ${canonical({ domain: 'example.com', path: '/article', variants: { amp: '/amp/article' } })}
  ${openGraph({
    title: "Article Title",
    description: "Article description",
    article: {
      authors: ['Author Name'],
      publishedTime: '2024-01-15T10:00:00Z',
      section: 'Technology'
    }
  })}
  ${author({ name: 'Author Name', profiles: { github: 'https://github.com/author' } })}
  ${robots({ maxSnippet: 160, maxImagePreview: 'large' })}
  ${twitter({ card: 'summary_large_image', site: '@handle' })}
`;

// Complete content ecosystem
const contentSystem = (posts) => ({
  html: posts.map(post => html`...${openGraph(post)}...`),
  rss: feed({ format: 'rss', title: 'Blog', items: posts }),
  atom: feed({ format: 'atom', title: 'Blog', items: posts }),
  sitemap: sitemap({ domain: 'example.com', pages: posts.map(p => ({ path: p.slug })) })
});
```

Supports Open Graph, Twitter Cards, canonical URLs, robots directives, structured data, RSS/Atom feeds, and XML sitemaps with progressive complexity tiers.

## Architecture

**Core template processors:**

| Module  | Purpose                         | Advanced Features                                                           |
| ------- | ------------------------------- | --------------------------------------------------------------------------- |
| `html/` | XSS protection, event binding   | Progressive SEO generators (Open Graph, Twitter, Canonical, Author, Robots) |
| `css/`  | Minification, object transforms | Object-to-kebab-case conversion                                             |
| `md/`   | GitHub Flavored Markdown        | Context-aware composition + HTML/text rendering                             |
| `js/`   | Script tag variants, filtering  | Script generation utilities                                                 |
| `sh/`   | Shell command assembly          | Command composition                                                         |
| `sql/`  | Injection prevention            | Query building with escaping                                                |
| `xml/`  | Well-formed XML with escaping   | Feed generators (RSS/Atom) + XML sitemaps                                   |

**Performance optimization:**

Template processing uses tiered algorithms based on interpolation count: direct string return (0 values), concatenation (1 value), StringBuilder (2-3 values), pre-sized arrays (4+ values). Conditional whitespace trimming avoids unnecessary work.

**Import strategy:**

ESM sub-exports enable precise tree-shaking. Each module resolves directly without filesystem traversal, optimizing for both bundle size and runtime performance.

## Requirements

- **Node.js:** 22.5+ (leverages latest platform primitives)
- **Browsers:** ES2020+ (modern baseline, no legacy compromise)
- **Dependencies:** Absolutely zero

## The Raven's Beak

A raven's beak is surgically precise—built for extracting maximum value with minimal effort. Like the raven that efficiently processes complex materials into digestible forms, Beak transforms raw template strings into optimized output without unnecessary overhead.

## 🦅 Support RavenJS Development

If you find RavenJS helpful, consider supporting its development:

[![GitHub Sponsors](https://img.shields.io/badge/Sponsor%20on%20GitHub-%23EA4AAA?style=for-the-badge&logo=github&logoColor=white)](https://github.com/sponsors/Anonyfox)

Your sponsorship helps keep RavenJS **zero-dependency**, **modern**, and **developer-friendly**.

---

**Built with ❤️ by [Anonyfox](https://anonyfox.com)**