npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

jsxte

v3.3.1

Published

JSX-based html templating engine for browsers or Node environments.

Downloads

1,567

Readme

JSX Template Engine

NPM npm Libraries.io dependency status for latest release GitHub last commit

A JSX based html templating engine for browsers or Node environments.

  1. Getting started
    1. Installation
    2. Building
  2. Examples
  3. Asynchronous Components
  4. Context
    1. Example
    2. Provider/Consumer Pattern
  5. Error Boundaries
    1. Example
  6. toHtmlTag symbol
  7. DomRenderer
  8. JsxteRenderer
  9. Extending the typings
    1. Adding custom web component tags
    2. Adding a global html attribute
  10. Express JS View Engine
  11. Monkey-Patching type definitions
  12. Contributing

Getting started

Installation

npm i jsxte

or

yarn add jsxte

Building

To use the jsxte you will have to set up your transpiler to use this package for transforming the JSX syntax, if you use typescript for transpiling all you have to do is set these options in the tsconfig:

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "jsxte"
  }
}

If you use something else, like babel you will also need to adapt the configuration of that, for example: https://babeljs.io/docs/en/babel-plugin-transform-react-jsx#with-a-configuration-file-recommended

(See example configurations here).

Once you are done with that you can start writing your templates and rendering them.

import { createElement, renderToHtml } from "jsxte";

const Header: JSXTE.Component<{ label: string }> = (props) => {
  return <h1>{props.label}</h1>;
};

const App: JSXTE.Component<{ label: string }> = (props) => {
  return (
    <html>
      <head>
        <meta charset="utf-8" />
        <meta
          http-equiv="X-UA-Compatible"
          content="IE=edge"
        />
        <meta
          name="viewport"
          content="width=device-width, initial-scale=1"
        />
      </head>
      <body>
        <Header label={props.label} />
      </body>
    </html>
  );
};

const html = renderToHtml(<App label="Hello World!" />);
// OR
const html = renderToHtml(createElement(App, { label: "Hello World!" }));

Examples

Check out these example repositories:

Asynchronous Components

In case you use the templates in a server app in a Node environment you might want to include some data from the database in the html you serve to the client. To make it easier to fetch what's needed and marry it with the templates you can make your components asynchronous and send async requests from within them.

import { renderToHtmlAsync } from "jsxte";

const Header: JSXTE.Component = () => {
  return <h1>Hello World</h1>;
};

const ToDoList: JSXTE.Component = async () => {
  const todos = await fetchMyTodosFromDB();

  return (
    <table>
      <thead>
        <tr>
          <th>Label</th>
          <th>Is Done?</th>
        </tr>
      </thead>
      <tbody>
        {todos.map((todo) => (
          <tr>
            <td>{todo.label}</td>
            <td>{todo.isDone ? "yes" : "no"}</td>
          </tr>
        ))}
      </tbody>
    </table>
  );
};

const App: JSXTE.Component = () => {
  return (
    <html>
      <head>
        <meta charset="utf-8" />
        <meta
          http-equiv="X-UA-Compatible"
          content="IE=edge"
        />
        <meta
          name="viewport"
          content="width=device-width, initial-scale=1"
        />
      </head>
      <body>
        <Header />
        <h3>ToDo's:</h3>
        <ToDoList />
      </body>
    </html>
  );
};

// If your component contains an asynchronous component at any point, `renderToHtmlAsync` needs to be used instead of `renderToHtml`
const html = await renderToHtmlAsync(<App label="Hello World!" />);

Context

Context Map is a interface provided to each functional component that provides a mechanism for providing any arbitrary data to it's descendant. This is primarily to avoid the prop-drilling.

Example

import { defineContext } from "jsxte";

const myContext = defineContext<{ label: string }>();

const App: JSXTE.Component = (props, componentApi) => {
  // Set the context to a new value, all descendants of this component will have access to it
  componentApi.ctx.set(myContext, { label: "Hello" });

  return <Foo />;
};

const Foo: JSXTE.Component = (props, componentApi) => {
  let label = "";

  // Check if `myContext` is being provided by any of the ancestors
  if (componentApi.ctx.has(myContext)) {
    // Retrieve the context data
    label = componentApi.ctx.getOrFail(myContext).label;
  }

  return <p>{label}</p>;
};

Provider/Consumer Pattern

Context also provides a Provider and a Consumer components.

const MyContext = defineContext<string>();

const App: JSXTE.Component = () => {
  return (
    <MyContext.Provider value={"Hello World!"}>
      <div>
        <MyContext.Consumer
          render={(providedValue) => <h1>{providedValue ?? ""}</h1>}
        />
      </div>
    </MyContext.Provider>
  );
};

Error Boundaries

Error boundaries are components that catch errors thrown by their children and allow you to display a fallback UI instead of having the rendering outright fail.

Error boundaries work with both synchronous and asynchronous components. But the onError handler should never return an asynchronous component.

Example

import { ErrorBoundary, renderToHtml } from "jsxte";

class Boundary extends ErrorBoundary {
  render(props: JSXTE.ElementProps, componentApi: ComponentApi) {
    return <>{props.children}</>;
  }

  onError(
    error: unknown,
    originalProps: JSXTE.ElementProps,
    componentApi: ComponentApi,
  ) {
    return <h1>Something went wrong!</h1>;
  }
}

const FailingComponent: JSXTE.Component = () => {
  throw new Error("Unexpected failure!");
};

const html = renderToHtml(
  <div>
    <Boundary>
      <FailingComponent />
    </Boundary>
  </div>,
);

// html:
// <div>
//   <h1>Something went wrong!</h1>
// </div>

toHtmlTag symbol

Symobl.toHtmlTag is a special symbol that allows to determine how an object should be stringified when used as a child of a JSX element.

Example

class User {
  constructor(
    public id: string,
    public username: string,
    public email: string,
  ) {}

  [Symbol.toHtmlTag]() {
    return `User: ${this.username}`;
  }
}

const user = new User("001", "Johny", "[email protected]");

renderToHtml(<div>{user}</div>);

Result:

<div>User: Johny</div>

DomRenderer

DomRenderer renders given JSX into a DOM object. It requires a window object to be passed to the constructor.

import { DomRenderer } from "jsxte";

const renderer = new DomRenderer(window);
const divElement = renderer.render(<div>Hello World!</div>);

divElement.outerHTML; // <div>Hello World!</div>
window.document.body.appendChild(divElement);

JsxteRenderer

JsxteRenderer is a base class around which HTML and JSON renderer are built upon. This renderer requires a specific interface that provides methods for creating the final output format:

// T is the type of the renderer return value
export interface ElementGenerator<T> {
  createElement(
    type: string,
    attributes: Array<[attributeName: string, attributeValue: any]>,
    children: Array<T>,
  ): T;
  createTextNode(text: string | number | bigint): T;
  createFragment(children: Array<T>): T;
}

It is possible to render to other formats than HTML or JSON by providing a custom ElementGenerator implementation to the renderer.

Example

import { JsxteRenderer } from "jsxte";

class DomGenerator
  implements ElementGenerator<HTMLElement | Text | DocumentFragment>
{
  createElement(
    type: string,
    attributes: Array<[attributeName: string, attributeValue: any]>,
    children: Array<HTMLElement | Text | DocumentFragment>,
  ): HTMLElement | Text | DocumentFragment {
    const element = document.createElement(type);
    for (const [name, value] of attributes) {
      element.setAttribute(name, value);
    }
    for (const child of children) {
      element.appendChild(child);
    }
    return element;
  }

  createTextNode(
    text: string | number | bigint,
  ): HTMLElement | Text | DocumentFragment {
    return document.createTextNode(String(text));
  }

  createFragment(
    children: Array<HTMLElement | Text | DocumentFragment>,
  ): HTMLElement | Text | DocumentFragment {
    const fragment = document.createDocumentFragment();
    for (const child of children) {
      fragment.appendChild(child);
    }
    return fragment;
  }
}

const renderer = new JsxteRenderer(new DomGenerator());
const divElement = renderer.render(<div>Hello World!</div>);

Extending the typings

JSXTE should be able to parse any html attributes you put in, as well as custom web component tags, although you may see type errors if you use anything that is not defined in the library typings. If you wish to use them it is recommended you extend the typings to disable said errors.

Adding custom web component tags

To add a typing for a custom web component simply add a declare block in one of your project .ts or .tsx files, like this one:

declare global {
  namespace JSX {
    interface IntrinsicElements {
      "my-custom-web-component": {
        /* here include the attributes your component can take */
        "data-example-attribute"?: string;
      };
    }
  }
}

// with it it's possible to use this without type errors:
const MyComponent: JSXTE.Component = () => (
  <my-custom-web-component data-example-attribute="Hello">
  </my-custom-web-component>
);

Adding a global html attribute

There is a dictionary of html attributes that are available for every default html tag, that dictionary can be extended like so:

declare global {
  namespace JSXTE {
    interface BaseHTMLTagProps {
      "new-attribute"?: string;
    }
  }
}

// with it it's possible to use this without type errors:
const MyComponent = () => <div new-attribute="Hello"></div>;

Express JS View Engine

You can also use jsxte with the Express View Engine. To do that, use the expressExtend to add the engine support, specify the views directory and then use the express response method .render(). The .render() method takes the component props as it's second argument.

import express from "express";
import { expressExtend } from "jsxte";

const app = express();
expressExtend(app);

app.set("views", path.resolve(__dirname, "views"));

app.get("/", (_, resp) => {
  const indexProps = {
    /* ... */
  };
  resp.render("index", indexProps); // will render the `index.js` component located in the ./views file
});

For this approach to work, the JSX Components must be exported as defaults (ex. export default () => <div></div> or exports.default = () => <div></div>) and the views must be transpiled to .js files.

Monkey-Patching type definitions

It is possible to monkey-patch type definition of all HTML tags and add new attributes to them.

Extend prop types of a specific tag

The following adds a new attribute to the <div /> tag - data-my-attr:

declare global {
  namespace JSXTE {
    interface DivTagProps {
      "data-my-attr"?: string;
    }
  }
}

Extends prop of all html tags

The following adds a new attribute to all html tags - hx-post:

declare global {
  namespace JSXTE {
    interface BaseHTMLTagProps {
      "hx-post"?: string;
    }
  }
}

Change the accepted type for a specific attribute

The following adds a Function type to the onclick attribute of all html tags:

declare global {
  namespace JSXTE {
    interface AttributeAcceptedTypes {
      onclick?: Function;
    }
  }
}

Contributing

If you want to contribute please See CONTRIBUTING.md