API

globalState

Creates a global state that can optionally be persistent.

src/stores/example.ts

import { globalState } from '@codeleap/store'

export const state = globalState(value, config)

Parameters

• value: The initial state value.
• config (GlobalStateConfig): Optional configuration.
  • persistKey (string | null): If defined, it activates the persistence of the state.

globalState(...) wraps a writable nanostores atom, so the result still carries writable-store behavior such as listen(...), while adding CodeLeap-specific ergonomics like selector-based use(...), merge-aware object set(...), and array-store helpers.

Methods

The globalState is an atom that can be modified, so it includes all the methods described in nanostores

• use: React hook for consuming the global state. You can pass a selector to extract a specific value, which is useful for object states to avoid unnecessary re-renders:

src/stores/example.tsx

import { globalState } from '@codeleap/store'

const state = globalState({ value: 1, value2: 2 })

function Component() {
  const value1 = state.use(state => state.value)

  // re-renders if value1 changes and never if value2 changes

  return null
}

function Component2() {
  const values = state.use()

  // re-renders if value1 or value2 changes

  return null
}

• set: Updates the global state immutably.

For primitive stores, set(...) replaces the value:

src/stores/example.tsx

const count = globalState(1)

count.set(2)

For object stores, set(...) merges the partial update into the current object:

src/stores/example.tsx

const authState = globalState({
  authFinished: false,
  hasResolvedInitialAuth: false,
})

authState.set({ authFinished: true })

Use the callback form when the next value depends on the current value:

src/stores/example.tsx

const count = globalState(1)

count.set(current => current + 1)

Do not assume object set(...) replaces the whole object.

• get: Retrieves the global state.

src/stores/example.tsx

const count = globalState(1)

const value = count.get()

• value: Accesses the current value of the global state.

src/stores/example.tsx

const count = globalState(1)

const value = count.value

• reset: Replaces the whole store value exactly.

src/stores/example.tsx

const authState = globalState({
  authFinished: false,
  hasResolvedInitialAuth: false,
})

authState.reset({
  authFinished: false,
  hasResolvedInitialAuth: false,
})

reset(...) is the raw underlying store set, not a special restore-initial helper.

• listen: Inherited writable-store subscription method from nanostores.

src/stores/example.tsx

const count = globalState(1)

const unsubscribe = count.listen((current, previous) => {
  console.log(current, previous)
})

Array

If the state value is an array, you will have access to the default array methods for manipulation, in addition to the ones provided above.

src/stores/example.tsx

const items = globalState([] as string[])

items.push('first')
items.unshift('zero')

const upper = items.map(item => item.toUpperCase())

Important:

• array helpers only exist when the store value is actually an array
• array-store behavior is different from object-store merge behavior
• calling array methods on non-array stores throws

Persistence

Use persistKey when the store should survive app restarts on the same device:

src/stores/example.tsx

const themeState = globalState('light', {
  persistKey: 'theme',
})

Persistence here is local-device persistence. It should be used for client-owned state, not API-backed shared data.