Skip to main content

​
Overview

Zayne Labs Toolkit uses Changesets for versioning and changelog management. This guide will help you migrate between versions and understand breaking changes.

​
Current Version

The latest stable version of the toolkit packages is:
  • @zayne-labs/toolkit-core: v0.12.43
  • @zayne-labs/toolkit-react: v0.12.43
  • @zayne-labs/toolkit-type-helpers: v0.12.43

​
Package Structure Changes

The toolkit is now split into three separate packages for better modularity and tree-shaking.

​
From Legacy to v0.12.x

If you’re migrating from an older version where everything was in a single package, you’ll need to update your imports:
1

Update package dependencies

Install the specific packages you need:
# For core utilities
pnpm add @zayne-labs/toolkit-core

# For React hooks and utilities
pnpm add @zayne-labs/toolkit-react

# For TypeScript type helpers
pnpm add @zayne-labs/toolkit-type-helpers
2

Update your imports

Before:
import { copyToClipboard, useToggle, Prettify } from "@zayne-labs/toolkit";
After:
import { copyToClipboard } from "@zayne-labs/toolkit-core";
import { useToggle } from "@zayne-labs/toolkit-react";
import type { Prettify } from "@zayne-labs/toolkit-type-helpers";
3

Update type imports

All type imports should use the type keyword for better tree-shaking:
import type { Prettify, ValueOf } from "@zayne-labs/toolkit-type-helpers";

​
React Package Updates

​
Subpath Exports

The React package now uses subpath exports for better code splitting: 
// Main hooks (default export)
import { useToggle, useDebounce } from "@zayne-labs/toolkit-react";

// React utilities
import { composeRefs, mergeProps } from "@zayne-labs/toolkit-react/utils";

// Zustand helpers
import { createReactStore } from "@zayne-labs/toolkit-react/zustand";

// Zustand compatible version
import { createReactStore } from "@zayne-labs/toolkit-react/zustand-compat";

​
Peer Dependencies

The React package now requires React 19.x as a peer dependency. Make sure your project is using a compatible version.
{
  "peerDependencies": {
    "react": ">=19.0.0",
    "@types/react": ">=19.0.0"
  }
}

​
Breaking Changes Checklist

  • Single package split into three separate packages
  • Update imports to use package-specific paths
  • Install only the packages you need
  • All packages now use "type": "module"
  • Only ESM builds are provided
  • Ensure your project supports ESM modules
  • All packages are marked as "sideEffects": false
  • Enables better tree-shaking
  • No changes required from users
  • Minimum Node.js version is now 18.x
  • Update your environment if using an older version

​
Version Management

The toolkit uses Changesets for version management. To stay updated:
1

Check for updates

pnpm outdated @zayne-labs/toolkit-*
2

Update packages

pnpm update @zayne-labs/toolkit-core @zayne-labs/toolkit-react @zayne-labs/toolkit-type-helpers
3

Test your application

Run your tests to ensure everything works correctly:
pnpm test
pnpm lint:type-check

​
TypeScript Configuration

The toolkit requires TypeScript 5.9.x for optimal type inference.
Ensure your tsconfig.json is configured correctly: 
{
  "compilerOptions": {
    "target": "esnext",
    "module": "esnext",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

​
Getting Help

If you encounter any issues during migration:
  • Check the GitHub Issues
  • Review the package-specific documentation
  • Open a new issue with details about your migration problem

​
Next Steps

Tree-Shaking Guide

Learn how to optimize your bundle size

API Reference

Explore all available functions and hooks

Build docs developers (and LLMs) love

Get started for freeTalk to us