Shared Utils

Shared utility functions and helpers for the Substrate project.

For detailed usage documentation, see the Shared Utils documentation on the docs site.

Contributing

Prerequisites

• Node.js 20+ and Yarn
• Understanding of TypeScript and common utility patterns

Commands

# Build the package
nx build shared-utils

# Run tests
nx test shared-utils

# Run tests in watch mode
nx test shared-utils --watch

# Run tests with coverage
nx test shared-utils --coverage

# Lint the package
nx lint shared-utils

Project Structure

packages/shared-utils/
├── src/
│   ├── lib/
│   │   ├── logger.ts        # Server-side structured logging with Pino
│   │   ├── client-logger.ts # Browser-safe logging
│   │   └── formatters.ts    # Type formatting helpers
│   ├── index.ts             # Browser-safe exports
│   └── server.ts            # Server-only exports
├── docs/                    # Documentation (built to docs site)
└── README.md                # This file

Environment Variables

Logging Configuration

Variable	Description	Default
LOG_LEVEL	Logging level (trace, debug, info, warn, error, fatal)	info
NODE_ENV	Environment (development, production, test)	development

In development, logs are pretty-printed for readability. In production, logs are JSON formatted for parsing.

Key Utilities

• Logging - Structured logging with Pino (server-side)
• Client Logging - Browser-safe logging for React components
• Type utilities - Helper functions that work with shared-types
• Common helpers - Reusable utility functions

Browser/Node Compatibility

This package is compatible with both browser and Node.js environments through separate exports:

Export Path	Environment	Modules
shared-utils	Browser + Node	formatters, client-logger
shared-utils/server	Node only	logger (Pino-based)

Import Examples:

// Server-side (Next.js API routes, resolvers)
import { createLogger, createRouteLogger } from "shared-utils/server";

// Browser-safe (React components)
import { createClientLogger, formatUser } from "shared-utils";

Important: Do not import from shared-utils/server in browser code as it uses Node.js-specific APIs (Pino, process.stdout).

Adding New Utilities

1. Create or edit a file in src/lib/ for the appropriate category
2. Implement your utility function with TypeScript types
3. Add comprehensive tests
4. Export from src/index.ts (browser-safe) or src/server.ts (Node.js only)
5. Update documentation

Testing

All utilities should have comprehensive test coverage. Write tests that:

• Cover happy path scenarios
• Test edge cases and error conditions
• Verify type safety where applicable

Related Documentation

• Root README - Substrate overview
• Docs README - Documentation site
• Testing Documentation - Testing guidelines