@a-la/jsx

The JSX Transform For ÀLaMode And Other Packages.

Usage no npm install needed!

<script type="module">
  import aLaJsx from 'https://cdn.skypack.dev/@a-la/jsx';
</script>

README

@a-la/jsx

npm version Build status Node.js CI

@a-la/jsx is The JSX transform For ÀLamode And Other Packages.

yarn add @a-la/jsx
npm i @a-la/jsx

Table Of Contents

API

The package is available by importing its default function:

import jsx from '@a-la/jsx'

jsx(
  string: string,
  config=: !Config,
): string

Returns the transpiled JSX code into h pragma calls.

  • string* string: The code to transform.
  • config !Config (optional): Configuration object.

Config: Options for the program.

Name Type Description Default
quoteProps (boolean | string) Whether to surround property names with quotes. When the dom string is passed, it will only quote props for invoking html components, i.e. those that start with a lowercase letter (this is required for Closure Compiler when not providing externs to elements). false
prop2class boolean If a property name starts with a capital letter, the className of the VNode will be updated. false
classNames (!Array<string> | !Object) The list of properties to put into the className property. -
renameMap !Object<string, string> How to rename classes (only applies to prop2class and classNames). -
styles !Object<string, string> Rename these properties into styles, e.g., <el border-top="1px"> will become &lt;el style="border-top:1px">. The keys must be property names, and the values are either booleans, or a string that should be used for renaming of the CSS property, such as { borderTop: 'border-top' }. Check out @a-la/styles that provides such a map. -
warn (warning: string) => ? The function to receive warnings, e.g., when destructuring of properties is used on dom elements (for Closure Compiler). -
import { readFileSync } from 'fs'
import jsx from '@a-la/jsx'

const code = readFileSync('example/Component.jsx', 'utf8')
const res = jsx(code)
console.log(res)

Given the component's source code:

import RichTextArea from 'richtext'

const Title = <title>Example</title>

export const Component = ({
  align = 'right', tabs, img,
}) => {
  const props = {
    class: 'example',
    id: 'id',
  }
  return <div onClick={(e) => {
    e.preventDefault()
    alert('Hello World')
    return false
  }} role="aria-button">
    <Title/>
    <RichTextArea dynamic />
    {tabs.map((tab, i) => <span key={i}>{tab}</span>)}
    <p {...props} align={align}>
      Hello World!
      {img && <img src={img}/>}
    </p>
  </div>
}

The following result is achieved:

import RichTextArea from 'richtext'

const Title = h('title',{},`Example`)

export const Component = ({
  align = 'right', tabs, img,
}) => {
  const props = {
    class: 'example',
    id: 'id',
  }
  return h('div',{onClick:(e) => {
    e.preventDefault()
    alert('Hello World')
    return false
  }, role:"aria-button"},
    h(Title),
    h(RichTextArea,{dynamic:true}),
    tabs.map((tab, i) => h('span',{key:i},tab)),
    h('p',{...props,align:align},
      `Hello World!`
      ,img && h('img',{src:img}),
    ),
  )
}

The Transform

The transform is the Reg-Exp alternative to Babel's implementation of the JSX transform. We're not aware of any other alternatives, however this approach provides a light-weight solution for transforming JSX syntax for front-end and back-end rendering and static website generation. The lit-html is based on template strings, and does not provide html highlighting which is enabled in .jsx files. This makes JSX the standard of modern HTML templating. The service using the JSX does not have to be a react page, so that the transform can be used to server-side rendering which will always require serving HTML using a template. To achieve this in Node.js, the ÀLaMode transpiler can be used, whereas this package just exports a single function to perform the translation of the code.

The import and export statements will be temporally commented out when transpiling, otherwise V8 will throw an error when trying to detect where JSX syntax starts (see the method).

Classes

It's possible to make the transpiler extract property names and add them into the className property. If such property already exists, it will be updated. If it doesn't, it will be created. Moreover, when prop2class property is set, any property that starts with a capital letter will also be added to the class list. Finally, if you pass a rename map, the classes will be updated according to it.

The component to transpile:

export default function Classes() {
  return (<div Example hello world />)
}

The setup:

import { readFileSync } from 'fs'
import jsx from '../src'

const code = readFileSync('example/classes.jsx', 'utf8')
const res = jsx(code, {
  prop2class: true,
  classNames: ['hello', 'world'],
  renameMap: {
    hello: 'hi',
  },
})
console.log(res)

The output:

export default function Classes() {
  return (h('div',{  className:'Example hi world' }))
}

The Dynamic Method

This package will try to create a new Script (an import from the vm module) to find out where JSX syntax failed (first <). The location of the opening tag is therefore found out and the name of the tag extracted. With the name of the tag, the closing tag name can be found, and the contents inside parsed.

/Users/zavr/a-la/jsx/test/fixture/Component.jsx:2
  <div className={className}>
  ^

SyntaxError: Unexpected token <
    at createScript (vm.js:80:10)
    at Object.runInThisContext (vm.js:139:10)
    at Module._compile (module.js:617:28)
    at Object.Module._extensions..js (module.js:664:10)
    at Module.load (module.js:566:32)
    at tryModuleLoad (module.js:506:12)
    at Function.Module._load (module.js:498:3)
    at Function.Module.runMain (module.js:694:10)
    at startup (bootstrap_node.js:204:16)
    at bootstrap_node.js:625:3

Limitations

  • Cannot use <> in functions, and {} in comments e.g.,
    const C = ({ items }) => <div>
      {items.map((i, j) => {
        // stop when { 10 }:
        if (j > 10) return
        return <span>{i}</span>
      })}
    </div>
    
  • Cannot define components in export default { }, or use anything with }, e.g.,
    export default {
      'my-component'() {
        return <div>Hello World</div>
      },
      nested: { val: true },
    }
    </div>
    

Copyright

Art Deco © Art Deco™ for À La Mode 2020