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

jsx-pragmatic

v2.0.22

Published

Javascript module template.

Downloads

12,807

Readme

JSX Pragmatic

build status code coverage npm version

  • Build JSX templates
  • Decide at runtime how you want to render them
  • Easily build custom renderers - render to HTML, DOM, or anything else!

Because JSX is pretty useful, even without React!

Build an abstract jsx component

First we'll build a small component. We're not tying ourselves to any particular framework yet, or any render target.

/* @jsx node */

import { node } from 'jsx-pragmatic';

function Login({ prefilledEmail }) {
  return (
    <section>
      <input type="text" placeholder="email" value={prefilledEmail} />
      <input type="password" placeholder="password" />
      <button>Log In</button>
    </section>
  );
}

Render on the server

Let's say we're on the server-side, and we want to render the jsx to html to serve to a client. Just pass html() to the renderer:

/* @jsx node */

import { node, html } from 'jsx-pragmatic';
import { Login } from './components'

function render() {
  return (
    <Login prefilledEmail='[email protected]' />
  ).render(html());
}

Render on the client

Now let's render the same jsx template on the client-side, directly to a DOM element:

/* @jsx node */

import { node, dom } from 'jsx-pragmatic';
import { Login } from './components'

function render() {
  return (
    <Login prefilledEmail='[email protected]' />
  ).render(dom());
}

Render in a React app

Or if we're using the same component in React, we can render it as a React component:

/* @jsx node */

import { node, react } from 'jsx-pragmatic';
import { Login } from './components'

function render() {
  return (
    <Login prefilledEmail='[email protected]' />
  ).render(react({ React }));
}

Render in a Preact app

Or if we're using the same component in Preact, we can render it as a Preact component:

/* @jsx node */

import { node, preact } from 'jsx-pragmatic';
import { Login } from './components'

function render() {
  return (
    <Login prefilledEmail='[email protected]' />
  ).render(preact({ Preact }));
}

Write your own renderer

Renderers are just functions!

  • Write a factory like customDom. This will take some options and return our renderer.
  • Return a renderer which takes name, props and children and renders them in whatever way you want!

This example renders the jsx directly to DOM elements:

/* @jsx node */

import { node, NODE_TYPE } from 'jsx-pragmatic';
import { Login } from './components'

function customDom({ removeScriptTags } = { removeScriptTags: false }) {

  let domRenderer = (node) => {
    if (node.type === NODE_TYPE.COMPONENT) {
      return node.renderComponent(domRenderer);
    }

    if (node.type === NODE_TYPE.TEXT) {
      return document.createTextNode(node.text);
    }

    if (node.type === NODE_TYPE.ELEMENT) {
      if (removeScriptTags && node.name === 'script') {
        return;
      }

      let el = document.createElement(node.name);

      for (let [ key, val ] of Object.entries(node.props)) {
        el.setAttribute(key, val);
      }

      for (let child of node.children) {
        el.appendChild(child.render(domRenderer));
      }

      return el;
    }
  }

  return domRenderer;
}

Then when you're ready to use your renderer, just pass it into .render() and pass any options you want to use to configure the renderer.

function render() {
  return (
    <Login prefilledEmail='[email protected]' />
  ).render(customDom({ removeScriptTags: true }));
}

Use Fragments

You can either import Fragment from jsx-pragmatic:

/* @jsx node */

import { node, Fragment } from 'jsx-pragmatic';

function Login({ prefilledEmail }) {
  return (
    <Fragment>
      <input type="text" placeholder="email" value={prefilledEmail} />
      <input type="password" placeholder="password" />
      <button>Log In</button>
    </Fragment>
  );
}

Or use the @jsxFrag comment, and the new <> </> syntax for Fragments, providing you're using Babel 7:

/* @jsx node */
/* @jsxFrag Fragment */

import { node, Fragment } from 'jsx-pragmatic';

function Login({ prefilledEmail }) {
  return (
    <>
      <input type="text" placeholder="email" value={prefilledEmail} />
      <input type="password" placeholder="password" />
      <button>Log In</button>
    </>
  );
}

Why?

JSX is a neat way of parsing and compiling templates to vanilla javascript. Right now most people use JSX with React. But in reality, the technology is decoupled enough from React that it can be used to render anything:

  • HTML
  • XML
  • DOM Nodes

This library helps you do that.

Can't you do that with Babel?

Yep, Babel provides a neat pragma option which lets you choose what your jsx is compiled to; if you don't want to use React.createElement, you can write your own pragma to convert the jsx to anything else.

The only problem with that is, the decision of which pragma to use is made entirely at build-time. Let's say you have a template which needs to be:

  • Rendered as an html string on the server side.
  • Rendered directly as a DOM element in some client environments.
  • Rendered as a React component in other client environments.

jsx-pragmatic helps you achieve that by allowing you decide when you render what your jsx should be transformed into.

It also abstracts away some of the stuff in jsx that's a little tricky to deal with; like nested children arrays, dealing with basic element vs function components, and fragments -- leaving you to focus on the renderer logic.

Quick Start

Install

npm install --save jsx-pragmatic

Getting Started

  • Fork the module
  • Run setup: npm run setup
  • Start editing code in ./src and writing tests in ./tests
  • npm run build

Building

npm run build

Tests

  • Edit tests in ./test/tests

  • Run the tests:

    npm run test

Testing with different/multiple browsers

npm run karma -- --browser=PhantomJS
npm run karma -- --browser=Chrome
npm run karma -- --browser=Safari
npm run karma -- --browser=Firefox
npm run karma -- --browser=PhantomJS,Chrome,Safari,Firefox

Keeping the browser open after tests

npm run karma -- --browser=Chrome --keep-open

Publishing

Before you publish for the first time:
  • Delete the example code in ./src, ./test/tests and ./demo
  • Edit the module name in package.json
  • Edit README.md and CONTRIBUTING.md
Then:
  • Publish your code: npm run release to add a patch
    • Or npm run release:path, npm run release:minor, npm run release:major