Skip to main content

​
Welcome Contributors

Thank you for your interest in contributing to Zayne Labs Toolkit! This guide will help you get started with development and understand our workflows.
The toolkit is an open-source project maintained by Ryan Zayne. We welcome contributions from developers of all skill levels.

​
Getting Started

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Node.js: v18.x or higher
  • pnpm: v10.28.2 (package manager)
  • Git: For version control

​
Development Setup

1

Fork and clone the repository

git clone https://github.com/zayne-labs/toolkit.git
cd toolkit
2

Install dependencies

The project uses pnpm workspaces:
pnpm install
3

Build all packages

pnpm build
4

Verify setup

Run tests to ensure everything is working:
pnpm test

​
Project Structure

The repository is organized as a monorepo using Turborepo: 
toolkit/
├── packages/
│   ├── toolkit-core/          # Core utilities and functions
│   ├── toolkit-react/         # React hooks and utilities
│   └── toolkit-type-helpers/  # TypeScript type utilities
├── apps/
│   └── dev/                   # Development playground
├── .changeset/                # Changesets for versioning
├── .github/                   # GitHub Actions workflows
└── turbo.json                 # Turborepo configuration

​
Development Workflow

​
Available Scripts

Root-level scripts: 
# Build all packages
pnpm build

# Build in development mode
pnpm build:dev

# Build and test (with linting)
pnpm build:test

​
Package-Specific Development

To work on a specific package: 
cd packages/toolkit-core

# Development mode
pnpm dev

# Run tests
pnpm test

# Type checking
pnpm lint:type-check

​
Making Changes

​
Adding New Features

1

Create a new branch

git checkout -b feature/your-feature-name
2

Develop your feature

  • Add your code in the appropriate package under src/
  • Export your function/hook from the package’s index.ts
  • Follow existing code patterns and conventions
3

Write tests

Create test files alongside your code:
yourFeature.test.ts
import { describe, expect, it } from "vitest";
import { yourFeature } from "./yourFeature";

describe("yourFeature", () => {
  it("should work correctly", () => {
    expect(yourFeature()).toBe(expected);
  });
});
4

Add TypeScript types

Ensure all functions have proper TypeScript types:
export const yourFeature = <T>(input: T): T => {
  // Implementation
};

​
Code Quality Standards

  • Use TypeScript 5.9.x features
  • Prefer type inference over explicit types
  • Use type for object shapes, interface for extensible contracts
  • Avoid any - use unknown or proper types
  • Export types separately from implementation
  • Write tests for all new features
  • Use Vitest for unit tests
  • Test edge cases and error conditions
  • Maintain or improve code coverage
  • Use happy-dom for browser environment tests
  • Follow the ESLint configuration
  • Use Prettier for formatting (automatic via lint-staged)
  • Use meaningful variable and function names
  • Add JSDoc comments for public APIs
  • Keep functions small and focused
  • Monitor bundle size with size-limit
  • Avoid unnecessary dependencies
  • Use tree-shakeable exports
  • Consider lazy loading for heavy features

​
Commit Guidelines

The project uses Husky for pre-commit hooks:

​
Pre-commit Checks

lint-staged.config.js
export default {
  "*.{js,ts,jsx,tsx}": () => "pnpm lint:eslint:root",
  "*.{ts,tsx}": () => ["pnpm test", "pnpm lint:type-check"],
  "package.json": () => "pnpm lint:publint",
  "packages/**/*.{js,ts,jsx,tsx}": () => "pnpm lint:size",
};
Before committing, the following checks run automatically:
  1. ESLint on changed files
  2. Tests for TypeScript files
  3. Type checking
  4. Bundle size validation
  5. Package.json validation

​
Commit Message Format

Use clear, descriptive commit messages: 
# Good examples
git commit -m "feat: add useLocalStorage hook"
git commit -m "fix: resolve debounce timing issue"
git commit -m "docs: update API reference for createStore"
git commit -m "refactor: simplify throttle implementation"

# Bad examples
git commit -m "update stuff"
git commit -m "fix bug"

​
Changesets

The project uses Changesets for version management.

​
Creating a Changeset

When your PR includes user-facing changes:
1

Run changeset command

pnpm changeset
2

Select affected packages

Choose which packages your changes affect:
  • @zayne-labs/toolkit-core
  • @zayne-labs/toolkit-react
  • @zayne-labs/toolkit-type-helpers
3

Choose version bump

Select the type of version bump:
  • patch: Bug fixes and small changes
  • minor: New features (backwards compatible)
  • major: Breaking changes
4

Write changeset summary

Describe your changes for the changelog:
Add useLocalStorage hook for persistent state management

This hook provides a simple way to sync React state with localStorage,
including automatic serialization and type-safety.

​
Continuous Integration

The project uses GitHub Actions for CI/CD:

​
Automated Checks

Lint and Type Check

Runs ESLint and TypeScript checks on all PRs

Size Limit

Validates bundle sizes stay within limits

Release Preview

Publishes preview releases via pkg.pr.new

Dependency Review

Scans for security vulnerabilities

​
Test Release

Every PR automatically gets a test release published via pkg.pr.new:
.github/workflows/release-and-publish(pkg.pr.new).yml
- name: Deploy and test release via pkg.pr.new
  run: pnpm release:test
You can test your changes before merging: 
# Install from test release
pnpm add https://pkg.pr.new/@zayne-labs/toolkit-core@<pr-number>

​
Pull Request Process

1

Prepare your PR

  • Ensure all tests pass
  • Add changeset if needed
  • Update documentation
  • Write clear PR description
2

Submit PR

  • Push your branch to GitHub
  • Open a pull request against main
  • Fill out the PR template
  • Link any related issues
3

Code Review

  • Wait for maintainer review
  • Address any feedback
  • Keep PR up to date with main
4

Merge

  • Once approved, your PR will be merged
  • Changesets will handle versioning
  • Changes will be published automatically

​
Release Process

Releases are automated using Changesets:
  1. When PRs with changesets are merged, a “Version Packages” PR is created
  2. This PR updates version numbers and CHANGELOG files
  3. When merged, packages are automatically published to npm
  4. Release notes are generated via changelogithub

​
Getting Help

GitHub Discussions

Ask questions and share ideas

GitHub Issues

Report bugs and request features

Contributing Guidelines

Detailed contribution guidelines

Code of Conduct

Community guidelines

​
Recognition

All contributors are recognized in:
  • GitHub contributors page
  • Release notes
  • Project README
Thank you for contributing to Zayne Labs Toolkit!

Build docs developers (and LLMs) love

Get started for freeTalk to us