croct-nanostores

Croct + Nanostores
Reactive, type-safe atoms for Croct personalized content.
_{by Fryuni (Luiz Ferraz) · Unofficial community library}

Documentation · Releases · Report Bug · Request Feature

---

Croct Nanostores bridges Croct's personalization engine with Nanostores, giving you reactive atoms that deliver personalized content to any UI framework.

Why Croct Nanostores?

• Framework-agnostic — One store, every framework. Works with React, Vue, Solid, Preact, and Svelte through the Nanostores ecosystem.
• Type-safe — Full TypeScript support with Croct's type generation. Slot IDs, fallback content, and component props are all validated at compile time.
• Fault-tolerant — Atoms always hold renderable content. Fetches fail silently to your fallback; loaded content is never lost on refresh errors.
• Auto-refreshing — Content can update automatically when user behavior changes (sign-in, profile update, cart modification, and more). Enable the auto-refresh-atom plugin when initializing Croct to opt in.
• Reactive attributes — Use Nanostores atoms anywhere in the attributes object and content refreshes automatically whenever any of them update — ideal for currency pickers, user segments, or any dynamic context.
• Persistent — Content is cached in localStorage by default, so returning users see personalized content instantly.

Quick start

Install the package along with @croct/plug and your framework's Nanostores connector:

npm install croct-nanostores @croct/plug @nanostores/react

Initialize Croct and create a content atom:

import { croct, croctContent } from 'croct-nanostores';

croct.plug({
    appId: '<YOUR_APP_ID>',
    plugins: ['auto-refresh-atom'],
});

export const banner = croctContent('home-banner@1', {
    title: 'Welcome',
    subtitle: 'Explore our latest collection',
    ctaLabel: 'Shop now',
    ctaLink: '/products',
});

Use it in your component:

import { useStore } from '@nanostores/react';
import { banner } from './stores';

export function Banner() {
    const state = useStore(banner);

    return (
        <section>
            <h1>{state.content.title}</h1>
            <p>{state.content.subtitle}</p>
            <a href={state.content.ctaLink}>{state.content.ctaLabel}</a>
        </section>
    );
}

The atom renders your fallback immediately, fetches personalized content in the background, and re-renders your component when it arrives. If the fetch fails, the fallback stays — your UI never breaks.

Documentation

Visit the full documentation for:

• Getting started — Installation, initialization, framework setup, and type safety
• Content rendering — State lifecycle, persistence, auto-refresh, and fault tolerance
• API reference — Complete reference for croctContent, CroctAtom, and State
• Live demo — Multi-framework rendering from a single store

Contributing

Contributions to the package are always welcome!

• Report any bugs or issues on the issue tracker.
• For major changes, please open an issue first to discuss what you would like to change.
• Please make sure to update tests as appropriate.

Development

bun install         # Install dependencies
bun run build       # Build the library
bun run dev         # Watch mode
bun test            # Run tests

License

MIT