xastscript

4.0.0 · active · verified Sun Apr 19

xastscript is a utility library providing a hyperscript-like interface for programmatically creating xast (XML Abstract Syntax Tree) nodes. Similar to React's `createElement` or `hastscript` for HTML, it simplifies the creation of XML syntax trees by allowing nested function calls instead of verbose object literals. The current stable version is 4.0.0, which requires Node.js 16 or later and is exclusively ESM. It's part of the unified ecosystem and is primarily used when generating XML structures within code. Unlike `unist-builder` which handles generic unist nodes, `xastscript` is specifically tailored for XML elements, providing convenience for defining attributes and children in a more declarative way. Its release cadence typically involves minor and patch updates every few months, with major versions occurring less frequently, driven by breaking changes or significant feature additions.

Common errors

```
ERR_REQUIRE_ESM
```
cause Attempting to use `require()` to import `xastscript`, which is an ES Module.

fix Change `const { x } = require('xastscript');` to `import { x } from 'xastscript';`. Ensure your `package.json` includes `"type": "module"` if this is a Node.js project or use `.mjs` file extensions.
```
TypeError: xastscript_1.x is not a function
```
cause This error typically occurs when a CommonJS consumer attempts to use an ESM package that has been incorrectly transpiled or bundled, or when trying to default import a named export.

fix Verify your build setup handles ES Modules correctly. Always use named imports for `x` (e.g., `import { x } from 'xastscript';`). If using TypeScript, check `tsconfig.json` for `moduleResolution` and `module` settings.
```
TypeError: Cannot read properties of undefined (reading 'x')
```
cause This can happen if the `xastscript` module isn't resolved correctly, or if a global `x` is expected when it's not available, often due to a failed or incorrect import.

fix Double-check your `import { x } from 'xastscript';` statement for typos. Ensure `xastscript` is correctly installed in `node_modules`. If running in a browser, ensure `esm.sh` or similar CDN imports are correct and bundled if necessary.

Warnings

breaking xastscript v4.0.0 requires Node.js 16 or higher. Older Node.js versions are no longer supported.
Fix: Upgrade your Node.js environment to version 16 or later. If unable to upgrade, consider using `xastscript` v3.x which supports Node.js 12+.
breaking xastscript transitioned to an ESM-only package starting with v3.0.0. Direct CommonJS `require()` calls are no longer supported.
Fix: Refactor your imports to use ES Modules syntax (`import { x } from 'xastscript';`). Ensure your project is configured for ESM by setting `"type": "module"` in your `package.json` or by using `.mjs` file extensions. In CommonJS files, dynamic `import()` can be used.
breaking TypeScript types are now shipped directly with the package since v2.0.0. If you were using `@types/xastscript`, you should remove it. V4.0.0 specifically updated `@types/xast`, potentially requiring updates in related type definitions.
Fix: Remove `@types/xastscript` from your `devDependencies`. Ensure your `tsconfig.json` correctly resolves types from `xastscript` itself. Review and update any explicit dependencies on `@types/xast`.
gotcha The `x` function can serve as a JSX pragma, allowing XML-like syntax directly in your code. This requires specific configuration in your TypeScript or Babel setup.
Fix: To use JSX with `xastscript`, configure your `tsconfig.json` (for TypeScript) or Babel presets. For example, in `tsconfig.json`: `"compilerOptions": { "jsx": "react-jsx", "jsxFactory": "x", "jsxFragmentFactory": null }`.

Install

npm install xastscript npm
yarn add xastscript yarn
pnpm add xastscript pnpm

Imports

x
wrong:
```
const { x } = require('xastscript')
```
correct:
```
import { x } from 'xastscript'
```
xastscript is ESM-only since v3.0.0. For Node.js, ensure your environment supports ES Modules or use a dynamic import. v4.0.0 requires Node.js 16+.
Attributes
wrong:
```
import { Attributes } from 'xastscript'
```
correct:
```
import type { Attributes } from 'xastscript'
```
The `Attributes` type defines the expected shape of properties passed to the `x` function. Import it as a type.
Result
wrong:
```
import { Result } from 'xastscript'
```
correct:
```
import type { Result } from 'xastscript'
```
The `Result` type represents the possible return types of the `x` function (i.e., xast nodes). Import it as a type.

Quickstart

Demonstrates creating xast XML elements with attributes and children using both array and argument-based child passing, and integrating with `unist-builder` for non-element xast nodes like comments and processing instructions.

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: 456},
    x('name', 'Exile in Guyville'),
    x('artist', 'Liz Phair'),
    x('releasedate', '1993-06-22')
  )
);

// Combining with unist-builder for other xast nodes (comments, instructions, cdata):
console.log(
  x(null, [
    u('instruction', {name: 'xml'}, 'version="1.0" encoding="UTF-8"'),
    x('album', [
      u('comment', 'A fantastic rock album!'),
      x('name', 'Born in the U.S.A.'),
      x('description', [u('cdata', '3 < 5 & 8 > 13')])
    ])
  ])
);

view raw JSON →