Atomico 2.1.0 🎉

Atomico 2.1.0 Changelog 🎉

Welcome to Atomico 2.1.0! This release is a major step forward, bringing a powerful brand-new core rendering engine, significantly enhanced asynchronous hooks, and an industry-first CLI built specifically to support Agentic AI coding assistants.

🚀 Features & General Details

1. Core Virtual DOM & Reconciliation Engine Upgrade

Atomico's core has been revamped with a highly optimized virtual DOM rendering engine, improving the speed and reliability of UI updates out of the box.

• Virtual DOM Reconciliation: Full implementation of render and renderChildren routines to handle strict VNode diffing and child element reconciliation.
• Effect Management System: Deep improvements to how the lifecycle hooks map to component rendering internally.
• useRender Hook: A new advanced hook designed to provide manual control over rendering sub-trees or injecting custom rendering logic.

2. Robust Implementations of Core Hooks

This version finalizes the internal implementation of core react-like hooks designed specifically for standard web component behavior.

• Added native implementations for useState, useMemo, and useCallback.

⚡ Supercharged usePromise

The usePromise hook has been heavily upgraded to offer state-of-the-art async abstractions. It now accepts an Option Object as a third parameter, overriding the previous boolean-only autorun behavior.

• Configuration Object ({ autorun, memo }): You can now pass an object to explicitly define behaviors.
• Memoization (memo: true): By enabling memo, the hook will preserve the previous result or error in the component state while a new promise is actively pending. This is perfect to prevent UI flickering during background refreshes.
• Suspense Integration: Connects with suspense features for elegant loading states.
• Granular Timing Metrics: The state returned now includes startTime and endTime (timestamp identifiers) to easily calculate execution durations and measure performance.

Exhaustive Example: usePromise with memo and endTime metrics:

import { c, usePromise } from "atomico";

function UserProfile({ userId }) {
    // 1. We pass `{ memo: true, autorun: true }` to keep the previous `result`
    // intact while fetching data for a new `userId`.
    const promiseState = usePromise(
        async () => {
            const res = await fetch(`/api/users/${userId}`);
            return res.json(); // Simulate 1.5s delay...
        },
        [userId],
        { memo: true, autorun: true } // Support for the new config object
    );

    // Initial load state
    if (promiseState.pending && !promiseState.result) {
        return <host>Loading for the first time...</host>;
    }

    if (promiseState.error) {
        return <host>Error loading user data</host>;
    }

    // Calculate execution time dynamically using startTime and endTime
    const loadDurationMs = promiseState.endTime 
        ? (promiseState.endTime - promiseState.startTime) 
        : 0;

    return (
        <host>
            <div class={promiseState.pending ? "faded" : "visible"}>
                <h1>{promiseState.result.name}</h1>
                
                {/* Print the duration of the promise using the new timing metrics! */}
                {promiseState.fulfilled && (
                    <small>Data fetched in: {loadDurationMs}ms</small>
                )}
                
                {/* Notify the user if a background update is occurring via `memo` */}
                {promiseState.pending && <p>Refreshing data quietly...</p>}
            </div>
        </host>
    );
}

customElements.define("user-profile", c(UserProfile));

3. Atomico CLI & AI Agent Skills 🤖 (Industry First)

As AI tools become a daily driver for coding, Atomico 2.1.0 officially ships with command-line tools to train your LLMs in real-time.

• atomico CLI Added: A brand new package binary that handles automation.
• AI Skill Installer: Easily copy Atomico's highly advanced contextual instructions directly into your IDE (Cursor, Copilot, or Gemini) so they understand Atomico's unique APIs implicitly.

Example: Installing AI Skills via CLI

Execute the CLI to easily drop Atomico's AI-readable markdown skills into your project repo .agents or .cursor directories:

npx atomico install skills

4. Tooling & Testing Infrastructure

• Comprehensive Testing coverage: Massive automated unit-testing additions verifying rendering internals, the Context system, and Form-associated hooks.
• Code Formatting: Shipped prettier integrations and initialized internal documents plotting upcoming hook APIs.

---

⚠️ Breaking Changes

None.
Version 2.1.0 introduces no public-facing breaking changes. All Virtual DOM optimizations, VNode processing, and hook augmentations are fully backward-compatible with 2.0.x web components.

Atomico@two – 2.0.0 🎉🎊🚀

This release introduces significant structural changes to Atomico, including a unified component syntax, full support for the new form–associated lifecycle methods for Web Components, and new hooks.

A single syntax for components

Until Atomico 1.x, there were three different ways to declare components. Atomico 2 consolidates all of them into a single compact functional syntax, optimized for DX, documentation, and AI tooling compatibility.

1. New compact syntax — The only syntax allowed in Atomico 2

export const MyComponent = c(
  ({ message }) => {
    return <host />;
  },
  {
    props: { message: String },
  }
);

This syntax does not require imperative TypeScript, allowing Atomico to infer types, props, and rules automatically.

Version 2 adopts this syntax exclusively to unify documentation, simplify examples, and improve compatibility with AI-powered tools.

2. Traditional functional syntax (🔴 deprecated)

function myComponent({ message }: Props<myComponent>) {
  return <host />;
}
myComponent.props = { message: String };

export const MyComponent = c(myComponent);

Based on a React + PropTypes–like style, but relied on imperative TypeScript for validation.

3. Arrow function with explicit type definition (🔴 deprecated)

const myComponent: Component<{ message: string }> = ({ message }) => {
  return <host />;
};
myComponent.props = { message: String };

export const MyComponent = c(myComponent);

Likewise, this approach depended on imperative declarations to validate rules.

---

Features — Props

The new compact syntax enables significant improvements in how rules and props are declared.

New property type: event

import { event } from "atomico";

const MyComponent = c(
  (props) => (
    <host>
      <button onclick={props.ClickOnButton}></button>
    </host>
  ),
  {
    props: {
      message: String,
      ClickOnButton: event(),
    },
  }
);

Benefits:

• Atomico automatically infers event types.
• Enhanced autocompletion and TSX developer experience:

<MyComponent
  onClickOnButton={({ currentTarget }) => {
    currentTarget.message;
  }}
/>

• Events can be dispatched from the element instance:

myComponent.ClickOnButton();

---

Features — Hooks

Atomico 2 introduces new hooks and updates to lifecycle behavior:

• useParent
• useListener
• useNodes
• useSlot
• useRender
• useInternals
• useFormProps
• useFormValidity
• useFormSubmit
• useFormValue
• useFormDisabled
• useFormAssociated
• useFormReset

All of these integrate with the new declarative engine at the core. ()

---

Breaking Changes

1. Removal of the old event property within props configuration

Caution

The event() helper fully replaces the previous syntax, which no longer auto–dispatches events.

The following code is invalid in Atomico 2:

{
  props: {
    message: {
      type: String,
      event: { type: "ChangeMessage" },
    },
  },
}

2. Removal of useReducer

This hook has limited practicality in Web Component architecture. Users may request its return through an issue if needed.

3. SSR removed from the core

SSR (Server-Side Rendering) support has been removed from the core to keep it lightweight.
Compatibility with SSR-first tools like Next.js will continue through external packages, not the core.

4. Removal of html`` (template strings)

Atomico 2 standardizes the syntax on JSX/TSX, so the html`` template tag is removed from the core and from official documentation.

---

New hook core: more declarative and precise for testing

The hook system has been fully rewritten to provide fine–grained control over lifecycle behavior during testing.

Before

Chained, hard-to-read execution:

hooks.cleanEffects()()();

Now

Declarative execution based on internal events:

hooks.dispatch(KEY_EVENT);

This improves precision, simplifies testing, and allows explicit control over effects and subscriptions.

Constants available in atomico/test-hooks

1. EFFECT
2. LAYOUT_EFFECT
3. INSERTION_EFFECT
4. FORM_ASSOCIATED
5. FORM_DISABLED
6. FORM_RESET

These constants allow you to manipulate each lifecycle stage independently during unit tests.

---

📝 Recommendation

We recommend a progressive migration, since this version introduces a single component syntax, and some external packages — such as @atomico/hooks — still target version 1.7x.x.

You should consider using Atomico 2 if you do not depend on these older packages, or if your goal is to expand your component system or improve compatibility with React-based tools.

The objective of this migration is to provide developers and AI tools with a consistent, stable context to automate component generation with Atomico.

Package Compatibility and Storybook

• Packages such as @atomico/exports, @atomico/react, @atomico/vite, and @atomico/wrapper already support Atomico 2.
• For Storybook, we recommend using the official Web Components template, which works with Atomico 2 thanks to Vite and TSXM.
• You may also use the tsconfig file distributed in the @atomico/tsconfig package.

Workspaces

Atomico has fully migrated to Vitest as its primary testing ecosystem, replacing previous setups and enabling a faster, more modern environment aligned with Vite.

Additionally, a new developer-experience/ directory has been introduced. This folder contains use cases and tests that consume the atomico package API before it is published.

The purpose of this new space is to facilitate internal exploration of the package, validate real integration scenarios, and improve the development experience prior to releasing new versions.

Thank you for using Atomico — we hope you love this version!

Atomico 2.1.0 - beta

new virtual DOM feature.

This version introduces a simpler and more agnostic virtual DOM. The new virtual DOM depends on only two properties:

1. type
2. props

This makes it compatible with Next and Turbopack’s extended compilation of node_modules, which can otherwise break or rename atomico/jsx-runtime into react/jsx-runtime.

Fix scripts npm

2.0.2-beta

2.0.2-beta

This version fixes some bugs from the beta.

1. Fix the boolean type assignment with a default value.
2. Fix the TypeScript types for useSlot and useNodes — they now infer automatically without needing to use InstanceType.
3. DOC A new documentation and examples schema has been added, making integration with AI much easier.

Note

This version is entering the testing phase in real-world applications under controlled environments before being released as latest.

Welcome to Atomico 2 (Beta)🎉.

This version includes BREAKING CHANGES for a faster, more mature, and easier development experience.

With this release, we achieved:

1. Unifying the component syntax into a single format.
2. Improving interactions with forms.
3. Adding new hooks that will boost the creation of your web components.

Unifying the component syntax into a single format

At first, Atomico offered 3 different ways to write components. We decided to stick with just one, so learning is simple and sustainable. In fact, you probably already know this syntax, but now it has a new superpower: the form property.

import { c, css } from "atomico";

const MyComponent = c(({ message }) => <host shadowDom>{message}</host>, {
    // Want to work with forms or the ElementInternals API? Easy, just use 👇
    form: true,
    // Bring your components to life with easy-to-declare reactivity.
    props: { message: String },
    // Style it however you want 💅.
    styles: css`
        :host {
            font-size: 2rem;
        }
    `
});

This syntax isn’t new for Atomico users, but now it has a new config: the form property.

Interacting with forms

Atomico now makes it easier to work with forms, expanding your component’s lifecycle with new hooks 🎣🎉.

useFormProps()

This hook syncs 2 props (by default name and value). The idea is to help your component behave just like a regular input.

To use this hook, your config should look something like this:

import { c, useFormProps } from "atomico";

const MyInput = c(
    () => {
        const [value, setValue] = useFormProps();
        return (
            <host shadowDom>
                <input
                    oninput={({ currentTarget }) => {
                        setValue(currentTarget);
                    }}
                />
            </host>
        );
    },
    {
        form: true,
        props: {
            name: String,
            value: String
        }
    }
);

useFormValidity()

This hook makes form validation easier. With Atomico, you can build your own validations or delegate them to other inputs. For example:

import { c, useFormProps, useRef } from "atomico";
import { delegateValidity } from "atomico/utils";

const MyInput = c(
    () => {
        const [value = "", setValue] = useFormProps();
        const ref = useRef<HTMLInputElement>();
        const [, validity] = useFormValidity(
            () => delegateValidity(ref.current),
            [value]
        );
        return (
            <host shadowDom>
                <span>{!validity.valid && "🔴"}</span>
                <input
                    ref={ref}
                    required
                    minLength={3}
                    oninput={({ currentTarget }) => {
                        setValue(currentTarget);
                    }}
                />
            </host>
        );
    },
    {
        form: true,
        props: {
            name: String,
            value: String
        }
    }
);

The biggest advantage of this hook is that it stays in sync with the form, even if your component hasn’t interacted with it yet.

useFormValue()

This hook lets you set a value at the form level, but without the automatic rules of useFormProps. It’s perfect for more complex interactions where you decide:

1. What the name is.
2. When the value is set.
3. If you want to reset the value on your own terms.
4. Custom hooks: this hook is friendly for creating form values without needing to know the props.

import { useFormValue } from "atomico";

const [value, setValue] = useFormValue();

useFormSubmit()

This hook lets you listen for the submit event at the form level.

import { useFormSubmit } from "atomico";

useFormSubmit(() => {
    console.log("Form submit!");
});

useFormAssociated

Lets you know if your component has been associated with a form.

useFormAssociated((form: HTMLFormElement) => {});

useFormDisabled

Lets you know if your component has been disabled for interactions by a parent.

useFormDisabled((disabled: boolean) => {});

useFormReset

Lets you know when the form has been reset.

useFormReset(() => {});

New hooks

Form hooks aren’t the only new thing. Now, at Atomico’s core, you also get:

useRender

This hook is a classic from @atomico/hooks and is now part of the core. It’s useful for rendering fragments in the Light DOM when your component uses shadowDom.

useRender(() => <img src={url} />, [url]);

useSlot

Another classic from @atomico/hooks, now in the core. It’s handy for getting the list of nodes associated with a slot.

const children = useSlot(ref); // ChildNode[]

return (
    <host shadowDom>
        <slot ref={ref} />{" "}
    </host>
);

useListener

This hook lets you listen to events from a reference.

useListener(ref, "click", (event) => {
    console.log("Click", event.target);
});

New event property type

import { event } from "atomico";

const MyButton = c(
    ({ clickOnMyButton }) => {
        return (
            <host>
                <button onclick={clickOnMyButton}>Click</button>
            </host>
        );
    },
    {
        props: {
            clickOnMyButton: event()
        }
    }
);

The goal is to give you an easy way to create custom events that you can dispatch whenever you want.

BREAKING CHANGES

SSR

SSR is no longer part of the core. We want a core that’s free from SSR, which will be developed separately as a new package.

html<host/>

The html tag is removed from the core, but you can use it as an extra package. We want a core that supports just one syntax: JSX, paving the way for a future rendering optimizer.

useReducer

With Atomico, state complexity is usually handled with just 2 hooks: useState and useProp.
If you feel you need to bring back this hook, open an issue and let us know!

atomico@1.79.2 🔧 - fixes types and context synchronization in case of edges

1. Fix first argument to useState at type level, example:

// BEFORE
const [state, setState] = useState<string>(()=>"welcome"); // ❌Typescript announces error
// BEFORE
const [state, setState] = useState<string>(()=>"welcome"); // ✅Typescript announces success

2. Context synchronization

While version 1.79 fixed cases where HTML-based synchronization is privileged, this fix fixes synchronization when using JSX, avoiding 2 renders when connecting to contexts 💪, example:

<MyParent>
    <MyContext>
       <MyChild/>
    </MyContext>
</MyParent>

Using JSX/TSX has better performance when synchronizing contexts,thanks to the fact that MyChild will be receiving the status at the time of mount.

atomico@1.79.1

This version applies fixes to improve component unmounting when using useSuspense and code reductions for the context API.

1. Internal fixes for the context API, reducing the code and logic.
2. Internal fixes for the suspense API, properly cleaning up the state upon unmounting.

Say hello to atomico@1.79 🎉🚀

This version has 2 core changes:

1. Improvements in the context API to achieve state synchronization in extreme and collaborative cases (When using Atomico within other libraries like React, Vue or Angular).
2. Enhancements in the suspense API, now allowing to properly observe and clean up promises resolved in nested components.

Fix : type declarations for refactor to context api

1.78.2

fix: ts