---
tagName: 10.3.0
name: 'Neo.mjs v10.3.0: Introducing HTML Templates'
publishedAt: '2025-08-02T14:37:23Z'
isPrerelease: false
isDraft: false
---
# Neo.mjs v10.3.0: Introducing HTML Templates

This release marks a major milestone in the evolution of Neo.mjs, introducing an intuitive, HTML-like syntax for building component VDOMs. This has been a significant undertaking, designed to lower the barrier to entry for new developers while holding true to the framework's core principles of performance and adherence to web standards.

This feature is the culmination of the work tracked in our public epic: [#7130](https://github.com/neomjs/neo/issues/7130).

## Key Feature: HTML Templates

You can now define a component's VDOM using familiar HTML-like syntax, powered by standard JavaScript Tagged Template Literals. This provides an alternative to the traditional JSON-based VDOM structure, making UI development more approachable.

```javascript
import { html } from '../../src/functional/util/html.mjs';
import Button   from '../../src/button/Base.mjs';

// Inside a component's render() method:
return html`
    <div class="my-container">
        <p>${this.myText}</p>
        <${Button} text="Click Me" handler="${this.onButtonClick}" />
    </div>
`;
```

### The Philosophy: Why Not JSX?

This new feature is built on a core Neo.mjs principle: **a commitment to a zero-builds development experience.**

-   **Standard JavaScript:** Unlike JSX, which requires a compiler, `html` templates are a standard JavaScript feature. Your code runs directly in the browser without a mandatory build step, providing an instant feedback loop.
-   **No Hidden Magic:** Logic is handled with plain JavaScript (`if/else`, `.map()`), not special template directives. What you write is what you get.

### The Dual-Mode Architecture

To achieve both developer convenience and production performance, the framework uses a sophisticated dual-mode approach:

1.  **Development Mode:** Templates are parsed live in the browser using `parse5`. This parser is **only loaded if templates are actually used**, ensuring zero overhead for applications that stick to the JSON VDOM.
2.  **Production Mode:** For `dist/esm`, `dist/dev`, and `dist/prod` builds, a powerful **build-time AST transformation** converts templates directly into optimized VDOM objects. This eliminates the `parse5` dependency from production builds entirely, resulting in **zero runtime parsing overhead** and maximum performance. The `enableHtmlTemplates` flag is also automatically set to `false` in production environments, ensuring that the runtime parser is never accidentally used.

As a developer convenience, if you name your template-generating method `render()`, the build process will automatically rename it to `createVdom()` for you, aligning with the framework's lifecycle methods while providing a familiar entry point.

## Foundational Enhancements

The introduction of HTML templates was made possible by a series of significant enhancements to the framework's core and build scripts:

-   **Component Lifecycle Integration (`src/functional/component/Base.mjs`):** The functional component base class was updated to recognize and process the new `HtmlTemplate` return type from `render()`, seamlessly integrating the parsing process into the component lifecycle.
-   **Runtime Parsing (`src/functional/util/HtmlTemplateProcessor.mjs`):** A new runtime processor that intelligently flattens nested templates, handles dynamic values, and uses `parse5` to convert the HTML string into a VDOM structure.
-   **Build-Time AST Processing (`buildScripts/util/astTemplateProcessor.mjs`):** A new, robust build-time processor that uses `acorn` to parse source code into an Abstract Syntax Tree (AST), replaces template literals with their VDOM object counterparts, and generates new, optimized code with `astring`.
-   **Webpack Integration (`buildScripts/webpack/loader/template-loader.mjs`):** A new Webpack loader that hooks the AST processor into the `dist/dev` and `dist/prod` build pipelines, applied only to the app worker where components live.

## New Documentation

To support this major new feature, we have added two comprehensive guides:

-   [Using HTML Templates](https://github.com/neomjs/neo/blob/dev/learn/guides/uibuildingblocks/HtmlTemplates.md): A guide focused on the syntax, features, and best practices for using the new template system.
-   [Under the Hood: HTML Templates](https://github.com/neomjs/neo/blob/dev/learn/guides/uibuildingblocks/HtmlTemplatesUnderTheHood.md): A deep dive into the philosophy and the dual-mode architecture, explaining how templates work in both development and production environments.

All changes combined into 1 commit: https://github.com/neomjs/neo/commit/0841e7e1a715c7afe67d07eebb8229e54828eedd

We are incredibly excited about this release and believe it makes Neo.mjs more powerful and accessible than ever. Please explore the new feature, read the documentation, and share your feedback!

Try it out by yourself:</br>
https://neomjs.com/examples/functional/nestedTemplateComponent/

<img width="1603" height="1292" alt="Screenshot 2025-08-02 at 17 01 25" src="https://github.com/user-attachments/assets/79cb4aad-b791-4b03-bf25-7147bbeeed39" />

https://neomjs.com/dist/esm/examples/functional/nestedTemplateComponent/

<img width="1606" height="1062" alt="Screenshot 2025-08-02 at 17 00 12" src="https://github.com/user-attachments/assets/7a21638f-cb68-4f28-ba04-6ebaccb3b3f3" />

https://neomjs.com/dist/development/examples/functional/nestedTemplateComponent/

<img width="1602" height="1179" alt="Screenshot 2025-08-02 at 17 06 24" src="https://github.com/user-attachments/assets/2c1d3ef7-2008-41a1-9025-2859d907ce2d" />
