Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

a-jsx-runtime

Package Overview
Dependencies
Maintainers
1
Versions
2
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

a-jsx-runtime

Frameworkless JSX Runtime

  • 1.2.0
  • latest
  • Source
  • npm
  • Socket score

Version published
Maintainers
1
Created
Source

a-jsx-runtime

A JSX runtime which allows using JSX templates to render HTML without the need for any frameworks such as react, preact etc. an allows optimized updates / re-renders by using a Virtual DOM implementation.

Difference to react's JSX flavor

  • class attribute instead of className
  • _ref attribute instead of ref
  • _key attribute instead of key
  • on-event attribute (e.g. on-click) instead of onEvent
  • Suspense: see Suspense section

Example


import { render, createRef, rawHtml, Slot, Suspense } from "a-jsx-runtime";

const existingHTMLElement = document.querySelector("#greetings");

const pendingRequest = fetchJSON("/api.json");

const inputRef = createRef<HTMLInputElement>();

function Card({ bg, children }) {
  const style = {
    "background-color": bg,
    border: "1px solid gray"
  };

  return (
    <div style={style}>
      <Slot name="content" hostsChildren={children}>
        <p>default content</p>
      </Slot>
      <Slot name="actions" hostsChildren={children} />
    </div>
  );
}

render(
  <>
    <Card bg="#a00">
      <p _slot="content">New Products!</p>
      <a _slot="actions" href="./shop">Buy Now</a>
    </Card>

    <input type="checkbox" _ref={inputRef} checked={true} />
    <p on-click={e => inputRef.current!.focus()}>label</p>

    <ul style="display: flex;">
      {["a", "b"].map(n => (
        <label _key={n}><input type="checkbox" />{n}</label>
      ))}
    </ul>

    {false && <p>not gonna render this</p>}

    {existingHTMLElement}

    <Suspense
      placeholder={<div>loading...</div>}
      promise={pendingRequest}
      template={response => <div>{rawHtml(response.richText)}</div>}
    />
  </>,
  document.querySelector("#container"),
);

// invoke the render call again e.g. when some data has been changed
render(...);

For another example see example.tsx.

Install

npm install a-jsx-runtime @babel/plugin-transform-react-jsx

Tooling setup

Webpack

  • add jsx parser to babel config. e.g
// webpack.config.js
module.exports = {
  ...
  module: {
    rules: [
      ...
      {
        test: /\.tsx$/,
        use: [
          {
            loader: 'babel-loader',
            options: {
              presets: [
                ...
              ],
              plugins: [
                ...
                [
                  "@babel/plugin-transform-react-jsx",
                  {
                    "runtime": "automatic", // add the `import` etc automatically.
                    "importSource": "a-jsx-runtime", // use jsx functions from the npm module
                  }
                ],
              ]
            }
          },
        ],
      },
    ]
  },
  resolve: {
    extensions: ['.ts', '.tsx', '.js', 'jsx', '.json']
  },
  ...
};
  • add "jsx": "preserve", to tsconfig.json.

Vite

  • use vite react plugin
// vite.config.js

import {defineConfig} from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig(() => ({
  plugins: [
    react(),
  ],
  // only needed when there is *no* tsconfig. otherwise the jsxImportSource will automatically be picked up
  esbuild: {
    jsxImportSource: "a-jsx-runtime",
  },
}));
  • tsconfig
// tsconfig.json

{
  "compilerOptions": {
    // ...
    "moduleResolution": "node16", // is currently needed for typescript to use package exports
    "jsx": "preserve",
    "jsxImportSource": "a-jsx-runtime",
  },
}

## Special props

### `_key`

When (re-)rendering a list with changing length or order, you can add a `_key` attribute with the unique identifier to each item, to make sure same rendered DOM Elements are re-used. This helps to maintain external changes (e.g. focus, user input, css animations ...)

example:

```jsx
<>
  {arr
    .filter(someDynamicFilter)
    .sort(sortFunction)
    .map(item => (
      <label _key={item.name}>
        <input type="checkbox" />
        {item.name}
      </label>
    ))
  }
</>

_ref

After the markup first time is rendered, the reference to the rendered html element will be passed to the _ref attribute.

example:

import { createRef } from "./jsx-runtime";

function Comp() {
  const ref = createRef<HTMLInputElement>();

  return (
    <>
      {/* use with createRef */}
      <input _ref={ref} />
      <my-label on-click={() => ref.current.focus() } />

      {/* use as callback*/}
      <input type="date" _ref={el => initDatePickerPlugin(el)} />
    </>
  );
}

_slot

Name of Function Components Slot element which will be replaced by the items having the prop. (see Slot section)

class

Class name of the html element. Which can be a string or an array for convince.

e.g.

<div class="container h-center">
  <button class={["btn", cta ? "primary" : "secondary"]} />
</div>

style

Style attribute for an html element. which can be a string or an object.

example:

const style = {
  outline: "1px solid gray",
  "padding-top": "10px",
  background: isActive && "red", // falsy values won't be rendered
}

<div style={style} />

Exports

render

render(markup , root, append?): void;

ParamTypeDefaultDescription
markupJSX | string | number | null | boolean | undefined | HTMLElementto be rendered content
rootHTMLElementcontainer for the content to be rendered into
[append]booleanfalseshould the provided markup be appended to the existing content, or replace root's child elements

Renders the provided jsx as markup inside the root html element.

import { render } from "a-jsx-runtime";

render(<div>{value}</div>, document.querySelector("#root"))

createRef

Creates a function which can be passed as the value for the _ref prop and later the rendered HTML Element be accessed via the .current property on it:

import { createRef } from "./jsx-runtime";

function Comp() {
  const ref = createRef<HTMLInputElement>();

  return (
    <>
      <input _ref={ref} />
      <my-label on-click={() => ref.current.focus() } />
    </>
  );
}

rawHtml

The provided string will be rendered as markup and not escaped / sanitized. Use this with caution because theoretically it allows broken html or even xss attacks

import { rawHtml } from "a-jsx-runtime";

const richText = await fetchCitation();

render(
  <article>{ rawHtml(richText) }</article>,
  el
);

Slot

Slots are named containers which are placeholders inside a function component and will be replaced by the content passed by the components consumer.

<Slot name={name} hostsChildren={hostsChildren}>{fallbackContent}</Slot>

ParamTypeDescription
namestringname to identify this slot when content is passed
hostsChildrenJSXChildprops.children from the parent component functions which contains the slotable elements
[fallbackContent]JSXChildfallback markup which will be rendered incase the component is used with out content having the _slot prop for this slot

example

function Dialog({children}) {
  return (
    <div>
      <Slot name="body" hostsChildren={children}>
        <p> fallback text </p>
      </Slot>
      <footer>
        <Slot name="footer" hostsChildren={children} />
      </footer>
    </div>
  );
 }

render (
  <Dialog>
    <h3 _slot="body"> Title </h3>
    <p _slot="body"> Description </p>
    <a _slot="footer" href="mailto:name@email.com">
      contact us
    </a>
  </Dialog>,
  element
)

Suspense

Component to render placeholder markup till some promise is resolved and the markup is updated

<Suspense placeholder={placeholder} promise={promise} template={template} />

ParamTypeDescription
placeholderJSXChildmarkup to be rendered during the time promise hasn't been resolved
promisePromisepromise which needs to be resolved for the actual markup to be rendered
templatefunctionfunction which will be called with promises resolve value and should return the desired jsx markup

example:

import { Suspense } from "a-jsx-runtime";

<Suspense
      placeholder={<PlaceholderTableRows />}
      promise={pendingRequest}
      template={(response) =>
        <TableRows rows={response.items} />
      }
/>

HTMLComment

Renders the provided text as html comments in the generated html.

import { HTMLComment } from "a-jsx-runtime";


<div>
  {/* @TODO: move to dedicated template */}
  <HTMLComment content=" start of personalized content " />
  <div />
</div>

will render

<div>
  <!-- start of personalized content -->
  <div></div>
</div>

Fragment

JSX Fragments allows sibling elements to be rendered without the need of a parent element. You usually don't have to explicitly import it, simply use

<>
  <p>1</p>
  <p>2</p>
</>

and JSX transformer will replace it with Fragments. But in case you want to pass some props, then you need to use it as:

import { Fragment } from "a-jsx-runtime";

  <Fragment _slot="info">
    <p>1</p>
    <p>2</p>
  </Fragment>

type JsxProps

Basic type for props object that Function Components can receive:

import { JsxProps } from "a-jsx-runtime";

function Dialog({ open = false, children }: JsxProps) {}

But it is always better if you define the prop type of the component explicitly, to allow type checking for the props when this component is used in other places.

Demo

Checkout repo and npm start to see the demo in the example folder in action.

Author

Github: @mbehzad

License

Copyright © 2021 mbehzad.
This project is MIT licensed.

Keywords

FAQs

Package last updated on 30 Jan 2023

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc