Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nuejs/nue/llms.txt

Use this file to discover all available pages before exploring further.

Nuedom is the rendering engine at the core of Nue. It takes HTML-extended templates, parses them into an AST, optionally compiles that AST to JavaScript, and renders the result to an HTML string. The package exposes four named exports that map directly to each stage of that pipeline.

​
Installation

bun add nuedom
# or
npm install nuedom

​
Exports

import { renderNue, parseNue, compileNue, createDocument } from 'nuedom'

​
parseNue(template)

Parses an HTML template string into a structured document object (AST). This is the first step in the pipeline — it tokenizes the source, resolves script blocks, detects component types, and returns metadata that the subsequent stages rely on. 
const doc = parseNue(template)
​
template
string
required
The raw HTML template string. May include <!doctype>, <script> blocks, YAML front-matter, and custom element tags.
Return value — a plain object with the following shape:
PropertyTypeDescription
libArrayArray of AST nodes, one per top-level element
rootobjectThe first node in lib — the primary component
scriptstringConcatenated content of all <script> blocks
doctypestringValue from <!doctype …> if present
is_libbooleantrue when the file contains only named/custom components
is_dhtmlbooleantrue when the template has event handlers or ES module imports
metaobjectYAML front-matter data attached to the document or to a component
Example: 
import { parseNue } from 'nuedom'

const template = `
<article>
  <h1>{ title }</h1>
  <p>{ body }</p>
</article>
`

const doc = parseNue(template)
console.log(doc.root.tag)   // '<article>'
console.log(doc.is_dhtml)   // false — no event handlers

​
compileNue(template)

Compiles a template string (or a pre-parsed document) into a JavaScript module source string. The output can be evaluated to obtain the component library array ready for runtime mounting. 
const js = compileNue(template)
​
template
string | object
required
Either the raw HTML template string or a document object previously returned by parseNue. When a string is passed, parseNue is called internally.
Return value — a string of JavaScript source. The string exports a lib constant and, if the template had a <script> block, the script’s contents are prepended. Example: 
import { compileNue } from 'nuedom'

const template = `
<counter>
  <p>Count: { count }</p>
  <button :onclick="count++">+</button>
  <script>
    count = 0
  </script>
</counter>
`

const js = compileNue(template)
// Returns something like:
// count = 0
// export const lib = [{ tag: '<counter>', ... }]
compileNue is primarily useful when you want to ship pre-compiled component libraries. For direct server-side rendering you can skip this step and call renderNue directly.

​
renderNue(template, opts?)

The primary server-side rendering function. Accepts either a raw template string or a pre-parsed AST and returns an HTML string. This is what Nuekit calls internally to render every page and component. 
const html = renderNue(template, opts)
​
template
string | object
required
The template to render. When a string is passed, parseNue is called internally and the first component in lib is rendered. When an AST object is passed the function skips parsing.
​
opts
object
Optional rendering options.
Return value — an HTML string representing the rendered output of the root component. Example: 
import { renderNue } from 'nuedom'

const template = `
<article class="post">
  <h1>{ title }</h1>
  <p>{ description }</p>
</article>
`

const html = renderNue(template, {
  data: {
    title: 'Hello World',
    description: 'First post using Nuedom.'
  }
})

// html => '<article class="post"><h1>Hello World</h1><p>First post using Nuedom.</p></article>'

​
createDocument()

Creates a minimal fake DOM environment used internally by renderNue during server-side rendering. The returned object implements enough of the browser document API — createElement, createTextNode, createDocumentFragment — for Nue’s rendering pipeline to work in a Node/Bun environment. 
const document = createDocument()
Return value — a fake document object. Nodes created by this document serialize to HTML strings via innerHTML.
You rarely need to call createDocument directly. renderNue sets global.document before rendering. The export exists for testing and for advanced use cases where you need to mount a Nue component into a custom document context.

​
The pipeline

The three main functions form a linear pipeline. You can enter at any step:
1

Parse — parseNue(template)

Tokenize the HTML string and build an AST. Extracts script blocks, resolves component names, and flags which features the template uses (event handlers, custom elements, etc.).
2

Compile — compileNue(doc)

Convert the AST into a JavaScript source string. Use this step when you want to pre-compile component libraries for delivery to the browser.
3

Render — renderNue(template, opts)

Mount the AST against a fake DOM, evaluate data bindings, and serialize to an HTML string. This is the step used for every server-side page render in Nuekit.
Full pipeline example: 
import { parseNue, compileNue, renderNue } from 'nuedom'

const template = `
<user-card>
  <img src="{ avatar }">
  <h2>{ name }</h2>
  <p>{ bio }</p>
</user-card>
`

// Step 1: Parse
const doc = parseNue(template)
console.log(doc.is_lib)     // true — only a custom element

// Step 2: Compile (optional — for browser delivery)
const js = compileNue(doc)

// Step 3: Render server-side
const html = renderNue(template, {
  data: { avatar: '/img/ada.jpg', name: 'Ada', bio: 'Engineer' }
})

​
Template syntax reference

Nuedom extends plain HTML with a small set of directives. All directives live in attributes, keeping the template parseable as standard HTML.

​
Data interpolation

Curly-brace expressions are evaluated against the data object: 
<p>Hello, { name }!</p>
<img src="{ avatarUrl }" alt="{ name }">

​
Event listeners

Prefix any event name with :on to attach a handler. The handler expression receives the event as $e: 
<button :onclick="count++">Increment</button>
<input :oninput="search = $e.target.value">
<form :onsubmit="handleSubmit($e)">...</form>

​
Loops

Use :for to render a list of elements from an array: 
<ul>
  <li :for="item in items">{ item.name }</li>
</ul>

​
Conditionals

Use :if, :else-if, and :else for conditional rendering: 
<p :if="user">Welcome, { user.name }</p>
<p :else>Please log in.</p>

​
Dynamic attributes

Prefix any attribute with : to evaluate its value as an expression: 
<div :class="isActive ? 'active' : ''">...</div>
<input :disabled="!isValid">

​
Component composition

A file may contain multiple top-level elements. Non-script elements become entries in lib. Custom elements reference siblings by tag name: 
<!-- avatar component -->
<avatar-img>
  <img src="{ src }" alt="{ alt }">
</avatar-img>

<!-- uses avatar-img -->
<user-card>
  <avatar-img src="{ user.avatar }" alt="{ user.name }">
  <h2>{ user.name }</h2>
</user-card>

Build docs developers (and LLMs) love

Get started for freeTalk to us