xast utility to create trees with ease.
- What is this?
- When should I use this?
- Install
- Use
- API
- JSX
- Types
- Compatibility
- Security
- Related
- Contribute
- License
This package is a hyperscript interface (like createElement from React and
such) to help with creating xast trees.
You can use this utility in your project when you generate xast syntax trees with code. It helps because it replaces most of the repetition otherwise needed in a syntax tree with function calls.
You can instead use unist-builder when creating any unist nodes and
hastscript when creating hast (HTML) nodes.
This package is ESM only. In Node.js (version 12.20+, 14.14+, 16.0+, 18.0+), install with npm:
npm install xastscriptIn Deno with esm.sh:
import {x} from 'https://esm.sh/xastscript@3'In browsers with esm.sh:
<script type="module">
import {x} from 'https://esm.sh/xastscript@3?bundle'
</script>import {u} from 'unist-builder'
import {x} from 'xastscript'
// Children as an array:
console.log(
x('album', {id: 123}, [
x('name', 'Born in the U.S.A.'),
x('artist', 'Bruce Springsteen'),
x('releasedate', '1984-04-06')
])
)
// Children as arguments:
console.log(
x(
'album',
{id: 123},
x('name', 'Exile in Guyville'),
x('artist', 'Liz Phair'),
x('releasedate', '1993-06-22')
)
)
// For other xast nodes, such as comments, instructions, doctypes, or cdata
// can be created with unist-builder:
console.log(
x(null, [
u('instruction', {name: 'xml'}, 'version="1.0" encoding="UTF-8"'),
x('album', [
u('comment', 'Great album!'),
x('name', 'Born in the U.S.A.'),
x('description', [u('cdata', '3 < 5 & 8 > 13')])
])
])
)Yields:
{
type: 'element',
name: 'album',
attributes: {id: '123'},
children: [
{
type: 'element',
name: 'name',
attributes: {},
children: [{type: 'text', value: 'Born in the U.S.A.'}]
},
{
type: 'element',
name: 'artist',
attributes: {},
children: [{type: 'text', value: 'Bruce Springsteen'}]
},
{
type: 'element',
name: 'releasedate',
attributes: {},
children: [{type: 'text', value: '1984-04-06'}]
}
]
}
{
type: 'element',
name: 'album',
attributes: {id: '123'},
children: [
{
type: 'element',
name: 'name',
attributes: {},
children: [{type: 'text', value: 'Exile in Guyville'}]
},
{
type: 'element',
name: 'artist',
attributes: {},
children: [{type: 'text', value: 'Liz Phair'}]
},
{
type: 'element',
name: 'releasedate',
attributes: {},
children: [{type: 'text', value: '1993-06-22'}]
}
]
}
{
type: 'root',
children: [
{type: 'instruction', name: 'xml', value: 'version="1.0" encoding="UTF-8"'},
{
type: 'element',
name: 'album',
attributes: {},
children: [
{type: 'comment', value: 'Great album!'},
{
type: 'element',
name: 'name',
attributes: {},
children: [{type: 'text', value: 'Born in the U.S.A.'}]
},
{
type: 'element',
name: 'description',
attributes: {},
children: [{type: 'cdata', value: '3 < 5 & 8 > 13'}]
}
]
}
]
}This package exports the identifier x.
There is no default export.
The export map supports the automatic JSX runtime.
You can pass xastscript to your build tool (TypeScript, Babel, SWC) as with
an importSource option or similar.
Create xast trees.
x(): rootx(null[, …children]): rootx(name[, attributes][, …children]): element
Qualified name (string, optional).
Case sensitive and can contain a namespace prefix (such as rdf:RDF).
When string, an Element is built.
When nullish, a Root is built instead.
Map of attributes (Record<string, string|number|boolean|null|undefined>,
optional).
Nullish (null or undefined) or NaN values are ignored, other values are
turned to strings.
Cannot be given if building a Root.
Cannot be omitted when building an Element if the first child is a
Node.
(Lists of) children (string, number, Node, Array<children>, optional).
When strings or numbers are encountered, they are mapped to Text
nodes.
If a Root node is encountered, its children are used instead.
xastscript can be used with JSX.
Either use the automatic runtime set to xastscript or import x yourself and
define it as the pragma (plus set the fragment to null).
The example above (omitting the second) can then be written like so:
/** @jsxImportSource x */
import {u} from 'unist-builder'
console.log(
<album id={123}>
<name>Born in the U.S.A.</name>
<artist>Bruce Springsteen</artist>
<releasedate>1984-04-06</releasedate>
</album>
)
console.log(
<>
{u('instruction', {name: 'xml'}, 'version="1.0" encoding="UTF-8"')}
<album>
{u('comment', 'Great album!')}
<name>Born in the U.S.A.</name>
<description>{u('cdata', '3 < 5 & 8 > 13')}</description>
</album>
</>
)You can use estree-util-build-jsx to compile JSX
away.
For Babel, use @babel/plugin-transform-react-jsx and either
pass pragma: 'x' and pragmaFrag: 'null', or pass importSource: 'xastscript'.
Alternatively, Babel also lets you configure this with a comment:
Babel also lets you configure this from code:
/** @jsx x @jsxFrag null */
import {x} from 'xastscript'
console.log(<music />)For TypeScript, this can be done by setting "jsx": "react",
"jsxFactory": "x", and "jsxFragmentFactory": "null" in the compiler options.
For more details on configuring JSX for TypeScript, see the
TypeScript JSX handbook page.
TypeScript also lets you configure this from code as shown with Babel above.
This package is fully typed with TypeScript.
It exports the additional types Child and Attributes.
Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 12.20+, 14.14+, 16.0+, and 18.0+. Our projects sometimes work with older versions, but this is not guaranteed.
XML can be a dangerous language: don’t trust user-provided data.
unist-builder— create any unist treehastscript— create a hast treexast-util-to-xml— serialize xast as XMLxast-util-from-xml— parse xast from XMLhast-util-to-xast— transform hast to xast
See contributing.md in syntax-tree/.github for
ways to get started.
See support.md for ways to get help.
This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.
