CRELT DOM Element Creation Utility

Common errors

• TypeError: crelt is not a function

  cause Attempting to import `crelt` using named import syntax (e.g., `import { crelt } from 'crelt';`) in an ES Module context, or incorrect destructuring in CommonJS.
  fix Use `import crelt from 'crelt';` for ES Modules or `const crelt = require('crelt');` for CommonJS, as `crelt` exports a single default function.

• Uncaught ReferenceError: crelt is not defined

  cause The `crelt` function was not imported or defined in the current scope before being used.
  fix Ensure `import crelt from 'crelt';` (or the equivalent CommonJS `require`) is at the top of your module or script file where `crelt` is being used.

• TypeError: Cannot set properties of undefined (setting 'onclick')

  cause This error can occur if `crelt` is called with an invalid first argument that is not a string (tag name) or an existing DOM element, leading to `crelt` returning `undefined` or a non-element, and then trying to set a property on it.
  fix Verify that the first argument passed to `crelt` is always a valid HTML tag name string (e.g., `'div'`, `'button'`) or a pre-existing DOM element.

Warnings

• gotcha CRELT distinguishes between string values for attributes (using `setAttribute`) and non-string values (using direct property assignment). Passing a string for an event handler like `onclick` will not work, as it will literally set the `onclick` attribute to a string, not assign a function to the property.
  Fix: Always pass functions (or other non-string types) for properties that expect them (e.g., `onclick: myHandler`). Use string values only for standard HTML attributes.
• gotcha Null or `undefined` values provided for attributes will be ignored and not set. Similarly, null or `undefined` elements within the children arguments or arrays of children will be skipped. While often convenient, this can mask issues if `null` is passed unintentionally.
  Fix: Be mindful of explicitly passing `null` or `undefined`. If conditionally adding children, ensure the condition correctly resolves to a valid element or nothing, e.g., `condition ? crelt('div', 'content') : null`.
• gotcha CRELT's primary use case is creating single DOM elements. While it allows arrays for children, it does not directly support creating DocumentFragments or multiple root-level elements from a single call in the way some templating systems might.
  Fix: To create multiple top-level elements, make separate `crelt` calls. To group multiple elements into a fragment before appending, you can manually create a `DocumentFragment` and then append `crelt`-generated elements to it.

Install

• npm install crelt npm
• yarn add crelt yarn
• pnpm add crelt pnpm

Imports

• crelt
  wrong:

  import { crelt } from 'crelt'

  correct:

  import crelt from 'crelt'

  CRELT exports a single default function. Attempting a named import will result in 'crelt is not a function' or similar errors in ESM contexts.
• crelt
  wrong:

  const { crelt } = require('crelt')

  correct:

  const crelt = require('crelt')

  For CommonJS environments, the `require` call directly assigns the default export. Destructuring is incorrect.

Quickstart

This quickstart demonstrates creating a hierarchical DOM structure using `crelt`, including dynamic attributes, event handlers, and different types of children (strings, other `crelt`-generated elements, and arrays of elements).

import crelt from 'crelt';

// Create a main container div
const container = crelt('div', { id: 'app-container', style: 'padding: 20px; border: 1px solid #ccc; font-family: sans-serif;' });

// Create a heading
const heading = crelt('h1', 'Welcome to CRELT Example!');

// Create a paragraph with some text
const paragraph = crelt('p', { class: 'info-text', style: 'color: #555;' },
  'CRELT is a tiny utility for creating DOM elements. ',
  'It simplifies the process of building complex structures directly in JavaScript.',
);

// Create a button with an event handler
let clickCount = 0;
const statusSpan = crelt('span', { id: 'status-message', style: 'margin-left: 10px; font-weight: bold; color: #007bff;' }, 'Not clicked yet.');

const button = crelt('button',
  {
    onclick: () => {
      clickCount++;
      statusSpan.textContent = `Button clicked ${clickCount} times!`;
    },
    style: 'padding: 10px 15px; background-color: #007bff; color: white; border: none; cursor: pointer; border-radius: 4px;',
  },
  'Click Me!'
);

// Combine button and status span into a div
const buttonContainer = crelt('div', { style: 'margin-top: 20px;' }, button, statusSpan);

// Create a list of items using an array for children
const items = ['Item A', 'Item B', 'Item C'];
const list = crelt('ul',
  { style: 'margin-top: 20px; padding-left: 20px;' },
  items.map(item => crelt('li', { style: 'margin-bottom: 5px;' }, item))
);

// Append all elements to the container
crelt(container, heading, paragraph, buttonContainer, list);

// Append the main container to the document body
document.body.appendChild(container);

console.log('DOM structure created and appended using CRELT.');