Quickstart

Get comwit running in a Next.js project in under 5 minutes.

1. Install

npm i comwit

2. Setup Provider

Create app/providers.tsx and wrap your root layout.

// app/providers.tsx
'use client'

import { useRouter } from 'next/navigation'
import { keepPreviousData, ComwitProvider } from 'comwit'
import { ReactNode } from 'react'

type AppContext = {
  router: { push: (href: string) => void }
}

export function Providers({ children }: { children: ReactNode }) {
  const router = useRouter()
  const context: AppContext = { router }

  return (
    <ComwitProvider
      context={context}
      defaultOptions={{
        query: {
          staleTime: 30_000,
          cacheTime: 120_000,
          gcTime: 180_000,
          placeholderData: keepPreviousData,
        },
        persist: {
          debounceMs: 100,
        },
      }}
    >
      {children}
    </ComwitProvider>
  )
}

// app/layout.tsx
import { Providers } from './providers'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  )
}

You can also configure global interceptors that apply to all action methods:

import { OnError, Log, ComwitProvider } from 'comwit'

<ComwitProvider
  context={context}
  defaultOptions={{
    query: { staleTime: 30_000 },
    interceptors: [
      OnError((e) => Sentry.captureException(e)),
      Log('info'),
    ],
  }}
>

ComwitProvider takes two props:

  • context — shared values (router, auth, etc.) available in all actions
  • defaultOptions.query — global query defaults (staleTime, cacheTime, placeholderData)
  • defaultOptions.persist — global persist defaults (debounceMs)
  • defaultOptions.interceptors — global interceptors applied to all action methods

Execution order: Provider interceptors (outermost) -> Class interceptors -> Method interceptors -> actual method.

3. Create state/.ai.md

Create src/state/.ai.md (or state/.ai.md). This file tells your LLM how to write state code. Copy the full template from the README.

This is what makes comwit different — the .ai.md file is the documentation. Your LLM reads it and generates correct state code on the first try.

4. Update CLAUDE.md

Add this to your project's CLAUDE.md:

## State Management

This project uses comwit. When working on files in state/, always read state/.ai.md first.

That's it. Your LLM now knows how to use comwit. Start building features by describing what state you need.

Next steps