Crel: Fast DOM Creation Utility

Common errors

• ReferenceError: crel is not defined

  cause The `crel` library was not correctly imported, loaded, or is out of the current scope, preventing access to its primary function.
  fix Ensure `crel` is properly imported using `import crel from 'crel';` (ESM), `const crel = require('crel');` (CommonJS), or that `crel.min.js` is loaded via a `<script>` tag in the HTML before use.

• TypeError: crel.proxy is not a function / crel.proxy is undefined

  cause This error occurs when attempting to use the `crel.proxy` API without properly accessing it from the default export, or if the runtime environment does not support ES6 Proxies.
  fix Verify that your runtime environment supports ES6 Proxies. For ESM, access the proxy API correctly via `import crelBase from 'crel'; const crelProxy = crelBase.proxy;`. For CommonJS, use `const crelProxy = require('crel').proxy;`.

Warnings

• gotcha Crel is designed for efficient creation of *new* DOM elements. While it's technically possible to pass existing DOM elements to `crel` for modification or rearrangement, this usage pattern is explicitly discouraged by the library's authors and can lead to unexpected behavior or inefficient DOM operations compared to native methods or libraries optimized for manipulation.
  Fix: For modifying or rearranging existing DOM elements, always use standard DOM manipulation methods (e.g., `appendChild`, `removeChild`, `insertBefore`) or a library specifically focused on efficient DOM manipulation and diffing.
• gotcha The standard `crel` API handles event listeners via a custom `crel.attrMap['on']` definition. Direct `onclick` or `oninput` attributes within the attribute object for the standard API will *not* automatically attach event handlers without this custom mapping being set up beforehand.
  Fix: To use declarative event handling with the standard `crel` API, you must first configure `crel.attrMap['on']` as demonstrated in the library's documentation. Alternatively, for direct `on<event>` attribute support, utilize the Proxy API (`crel.proxy`) which natively maps these attributes to event listeners, or attach events manually using `element.addEventListener()`.
• gotcha Crel extensively utilizes modern ES6 features (e.g., Proxies for its advanced API). Consequently, it is specifically intended for use in modern 'evergreen' browser environments. Applications targeting older or legacy browsers will require transpilation (e.g., via Babel) to ensure full compatibility and functionality.
  Fix: Ensure your project's build pipeline includes a transpilation step for JavaScript code (e.g., using Babel with appropriate presets) if supporting legacy browsers is a requirement. Otherwise, explicitly target modern browsers where ES6 features are natively supported.

Install

• npm install crel npm
• yarn add crel yarn
• pnpm add crel pnpm

Imports

• crel
  wrong:

  import { crel } from 'crel';

  correct:

  import crel from 'crel';

  Primary default export for the standard API, used for creating DOM elements. `crel` itself is a function.
• crel (CommonJS)
  wrong:

  import crel from 'crel';

  correct:

  const crel = require('crel');

  Standard CommonJS import for Node.js or Browserify environments where `require` is used.
• crel.proxy
  wrong:

  import { proxy } from 'crel';

  correct:

  import crelBase from 'crel'; const crelProxy = crelBase.proxy;

  Accesses the Proxy-based API variant from the default export, enabling cleaner syntax like `crelProxy.div(...)` for environments supporting ES6 Proxies.

Quickstart

This quickstart demonstrates both the standard `crel` function and its Proxy-based API. It shows how to create and append various DOM elements, including handling attributes and events, illustrating the different ways to attach event listeners based on the API variant used.

import crel from 'crel';

// Standard API usage
const standardButton = crel('button', {
    type: 'button',
    'data-action': 'standard-click' // Direct event attributes like 'onclick' won't work without crel.attrMap['on'] setup
}, 'Click Me (Standard)!');

const infoParagraph = crel('p', 'This element was created using the standard `crel` function syntax.');

const standardDiv = crel('div',
    { 'class': 'standard-example', style: 'padding: 15px; border: 1px solid #ccc; background-color: #f9f9f9;' },
    crel('h2', 'Standard Crel API'),
    infoParagraph,
    standardButton
);

// Attach event listener for the standard button (common alternative if attrMap['on'] isn't configured)
standardButton.addEventListener('click', () => alert('Standard API button clicked (via addEventListener)!'));

// Accessing the Proxy API from the default export
const crelProxy = crel.proxy;

// Proxy API usage
const proxyButton = crelProxy.button({
    type: 'button',
    onclick: () => alert('Proxy API button clicked!') // Proxy API handles 'onclick' directly as an attribute
}, 'Proxy Click Me!');

const proxyInfoParagraph = crelProxy.p('This element was created using the modern Proxy API for cleaner syntax.');

const proxyDiv = crelProxy.div(
    { 'class': 'proxy-example', style: 'margin-top: 20px; padding: 15px; border: 1px solid #cce; background-color: #f0f8ff;' },
    crelProxy.h2('Proxy Crel API'),
    proxyInfoParagraph,
    proxyButton
);

// Append elements to the document body (or a specific container)
document.body.appendChild(standardDiv);
document.body.appendChild(proxyDiv);

console.log('DOM elements created and appended to the document body.');