Skip to main content

Introduction

The Drift Common monorepo contains a suite of shared packages that provide essential functionality for building Drift Protocol applications. These packages are designed to work together seamlessly while maintaining clear separation of concerns.

Available Packages

@drift-labs/common

Core utilities, clients, and helpers for interacting with Drift Protocol

@drift-labs/react

React components, hooks, and providers for building Drift applications

@drift-labs/icons

Comprehensive icon library generated from Figma designs

Package Relationships

The packages have the following dependency structure:
All packages depend on @drift-labs/sdk and @solana/web3.js as peer dependencies.

Common Features

All packages in this monorepo share these characteristics:

TypeScript First

Every package is written in TypeScript with full type definitions included:
  • Type safety for all exported functions and components
  • IntelliSense support in modern IDEs
  • Compile-time error checking

ESM/CJS Support

Packages are built to support both module systems:
{
  "main": "./lib/index.js",
  "module": "./lib/esm/index.js",
  "types": "./lib/index.d.ts"
}

Browser Compatibility

All packages include browser-specific builds when needed, with polyfills for Node.js APIs.

Monorepo Structure

drift-common/
├── common-ts/          # Core utilities and clients
│   ├── src/
│   ├── package.json
│   └── tsconfig.json
├── react/              # React components and hooks
│   ├── src/
│   ├── package.json
│   └── tsconfig.json
├── icons/              # Icon components
│   ├── src/
│   ├── package.json
│   └── tsconfig.json
└── package.json        # Root package.json

Development Workflow

Building Packages

Each package can be built independently:
# Build all packages
bun run build

# Build specific package
cd common-ts && bun run build
cd react && bun run build
cd icons && bun run build

Linking for Local Development

To use packages locally during development:
# In the package directory
npm link

# In your project
npm link @drift-labs/common
npm link @drift-labs/react
npm link @drift-labs/icons

Running Tests

# Run tests for common-ts
cd common-ts && bun test

# Run tests with coverage
cd common-ts && bun test:ci

Version Management

All packages use semantic versioning. When making breaking changes, ensure major version bumps are coordinated across dependent packages.
Current versions:
  • @drift-labs/common: v1.0.39
  • @drift-labs/react: v1.0.0
  • @drift-labs/icons: v1.0.0

Best Practices

Import Patterns

Use named imports for better tree-shaking:
// Good
import { Config, Initialize } from '@drift-labs/common';
import { useSolBalance, DriftProvider } from '@drift-labs/react';
import { Add, ChevronDown } from '@drift-labs/icons';

// Avoid
import * as Common from '@drift-labs/common';

Peer Dependencies

Always install required peer dependencies:
npm install @drift-labs/sdk@^2.158.0-beta.0 @solana/[email protected]

TypeScript Configuration

Ensure your tsconfig.json includes:
{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

Contributing

For detailed contribution guidelines, see the Contributing Guide.

Package-Specific Guidelines

  • Ensure utilities are framework-agnostic
  • Add tests for all new functionality
  • Update exports in src/index.ts
  • Document all public APIs
  • Follow React hooks best practices
  • Add prop type documentation
  • Ensure components are accessible
  • Test with React 19
  • Icons are auto-generated from Figma
  • Use the bun icons script to regenerate
  • Maintain consistent naming conventions
  • Test icon rendering

Next Steps

Get Started with Common

Explore utilities and clients

Build with React

Learn about hooks and components

Use Icons

Browse the icon library

API Reference

View complete API docs

Build docs developers (and LLMs) love