shared-utils

Collection of common utilities for web applications. Features centralized configuration through OptionsManager and environment-aware utilities that work across client/server contexts.

📋 Table of Contents

• shared-utils
  • 📋 Table of Contents
  • Installation
  • Quick Start
    • Import Paths
    • Basic Setup
  • Available Modules
    • 📋 Utils
    • 🎨 Client Components
      • 📝 WYSIWYG Editor Components
    • 🚀 Server
  • Configuration
    • Centralized Configuration (Recommended)
    • Framework Examples
      • Next.js
      • Express.js
  • Command Line Tools
    • Dependency Manager
    • Package Scripts Integration
  • Usage Examples
  • Deployment Guide
    • 📖 Documentation
    • Quick Setup
  • Documentation
    • Package Structure

Installation

Add to your package.json:

{
  "dependencies": {
    "@user27828/shared-utils": "https://github.com/user27828/shared-utils.git#master"
  }
}

Or install via command line:

# Using yarn (recommended)
yarn add @user27828/shared-utils@https://github.com/user27828/shared-utils.git#master

# Using npm
npm install @user27828/shared-utils@https://github.com/user27828/shared-utils.git#master

🔝 Back to Top

Quick Start

Import Paths

Use specific import paths for clarity:

// ✅ Utils and configuration
import { log, turnstile, optionsManager } from "@user27828/shared-utils/utils";

// ✅ Client components (React/Next.js)
import {
  CountrySelect,
  LanguageSelect,
  FileIcon,
} from "@user27828/shared-utils/client";

// ✅ WYSIWYG Editor (requires @tinymce/tinymce-react and tinymce)
import { TinyMceEditor } from "@user27828/shared-utils/client/wysiwyg";

// ✅ Server functionality
import { verifyTurnstileTokenEnhanced } from "@user27828/shared-utils/server";

Basic Setup

import { optionsManager } from "@user27828/shared-utils/utils";

// Configure utilities
optionsManager.setGlobalOptions({
  log: {
    type: "client",
    client: { production: ["warn", "error"] },
  },
  turnstile: {
    siteKey: process.env.NEXT_PUBLIC_TURNSTILE_SITE_KEY,
    secretKey: process.env.TURNSTILE_SECRET_KEY,
  },
});

🔝 Back to Top

Available Modules

📋 Utils

Core utilities with environment detection and centralized configuration:

• Logging: Production-safe console wrapper
• Turnstile: Cloudflare bot protection integration
• OptionsManager: Unified configuration system
• isDev: Development environment detection utility

🎨 Client Components

React components and client-side helpers:

• Form Components: CountrySelect, LanguageSelect
• File Icons: FileIcon - MUI icons for 70+ file types and MIME types
• Helper Functions: Country/language utilities, CSV helpers

📝 WYSIWYG Editor Components

WYSIWYG components are available as an optional separate import to avoid forcing TinyMCE dependencies on projects that don't need them:

# First, install the required peer dependencies
yarn add @tinymce/tinymce-react tinymce

// Import WYSIWYG components separately
import { TinyMceEditor } from "@user27828/shared-utils/client/wysiwyg";

// Basic usage
<TinyMceEditor
  data={content}
  onChange={(value) => setContent(value)}
/>

Features:

• Conditional Loading: Components gracefully handle missing dependencies
• Lightweight: Main client export doesn't include TinyMCE bundle
• Flexible: Use TinyMceEditor for pre-configured setup

🚀 Server

Server-side functionality and Cloudflare Workers:

• Turnstile Verification: Token validation service
• Deployment Scripts: Automated Cloudflare Worker deployment
• Configuration Templates: Ready-to-use examples

Server utilities

• getClientIp(req): Robust helper to extract the client's IP address from a Request-like object. It checks common proxy headers (x-forwarded-for, x-real-ip, cf-connecting-ip, etc.), handles IPv6 formats (including bracketed addresses and IPv4-mapped IPv6 ::ffff:), and falls back to socket properties such as req.ip, req.connection.remoteAddress, or req.socket.remoteAddress.

Usage example:

import { getClientIp } from "@user27828/shared-utils/server";

const ip = getClientIp(req);

🔝 Back to Top

Configuration

Centralized Configuration (Recommended)

import { optionsManager } from "@user27828/shared-utils/utils";

optionsManager.setGlobalOptions({
  log: {
    type: "client",
    client: { production: ["warn", "error"] },
  },
  turnstile: {
    siteKey: process.env.NEXT_PUBLIC_TURNSTILE_SITE_KEY,
    secretKey: process.env.TURNSTILE_SECRET_KEY,
    widget: { theme: "auto", size: "normal" },
  },
});

Framework Examples

Next.js

// app/lib/utils-config.ts
import { optionsManager } from "@user27828/shared-utils/utils";

export function initializeUtils() {
  optionsManager.setGlobalOptions({
    turnstile: {
      siteKey: process.env.NEXT_PUBLIC_TURNSTILE_SITE_KEY!,
      secretKey: process.env.TURNSTILE_SECRET_KEY!,
    },
  });
}

Express.js

// server.js
import { optionsManager } from "@user27828/shared-utils/utils";

optionsManager.setGlobalOptions({
  log: { type: "server" },
  turnstile: { secretKey: process.env.TURNSTILE_SECRET_KEY! },
});

🔝 Back to Top

Command Line Tools

• killnode - Kills Express server node processes (ignores VS Code, Electron, etc.)
• yarn-upgrade - Interactive yarn upgrade with Cloudflare Pages compatibility
• dependency-manager - Manages portal: resolutions for local development vs. production builds

Dependency Manager

The dependency-manager.js script automatically handles portal: resolutions in package.json files based on the environment. This is essential for Cloudflare Workers which fail when portal: references exist in production.

Key Features:

• Auto-detects development vs. production environments
• Enables portal resolutions for local development
• Removes portal resolutions for production builds and CI/CD
• Supports monorepo structures (packages/, apps/, workers/, etc.)
• Works with both npm and yarn

Usage in Consuming Projects:

Option A - Automatic detection (recommended):

{
  "scripts": {
    "dev": "dependency-manager && yarn dev",
    "build": "dependency-manager && yarn build",
    "cf:deploy": "dependency-manager && wrangler deploy"
  }
}

Option B - Explicit control:

{
  "scripts": {
    "enable:portal": "dependency-manager --enable",
    "disable:portal": "dependency-manager --disable",
    "dev": "yarn enable:portal && yarn dev",
    "build": "yarn disable:portal && yarn build"
  }
}

Configuration:

Add a _portalConfig section to your package.json:

{
  "dependencies": {
    "@user27828/shared-utils": "https://github.com/user27828/shared-utils.git#master"
  },
  "_portalConfig": {
    "@user27828/shared-utils": "../path/to/shared-utils"
  }
}

Command Line Options:

• No args: Auto-detects environment
• --enable: Force enable portal resolutions
• --disable: Force disable portal resolutions

Package Scripts Integration

Add useful scripts to your package.json:

{
  "scripts": {
    "kill": "npx killnode -9",
    "upgrade": "npx yarn-upgrade-interactive --skip-server",
    "dev": "dependency-manager && npx killnode && your-dev-command",
    "build": "dependency-manager && your-build-command",
    "cf:deploy": "dependency-manager && wrangler deploy"
  }
}

🔝 Back to Top

Usage Examples

Complete examples are available in the /utils/examples/ directory:

• client-init.js - Client-side setup
• server-init.js - Server-side configuration
• express-middleware.js - Express.js integration
• turnstile-react-component.tsx - React component integration

🔝 Back to Top

Deployment Guide

For deploying Turnstile workers in your own projects:

📖 Documentation

• Worker Deployment Guide - Complete deployment strategies
• Example Integration - Step-by-step example

Quick Setup

# Set up Turnstile worker in your project
npx cf:setup-turnstile-worker --name "myapp-turnstile" --origins "https://myapp.com"

# Configure and deploy
cd workers/turnstile
wrangler secret put TURNSTILE_SECRET_KEY
./deploy-turnstile-worker.sh production

🔝 Back to Top

Documentation

• Utils Documentation - Complete API reference for logging, Turnstile, and OptionsManager
• Server Documentation - Server-side integration and Cloudflare Workers
• Deployment Guide - Complete deployment strategies
• Example Integration - Step-by-step integration example

🔝 Back to Top

---

Package Structure

├── utils/           # Core utilities (log, turnstile, OptionsManager)
├── client/          # React components and helpers
├── server/          # Cloudflare Workers and deployment scripts
├── bin/             # Command-line tools
└── examples/        # Complete integration examples

---

Thx "AI" for writing the tests and parts of the readme files. Now, plz don't kill me during the revolution. Thx!

---

Love, User27828 ❤️

🔝 Back to Top