@pnkx-lib/core

Core utilities and hooks for PNKX UI library with optimized tree shaking support.

🎯 Features

• Tree Shakable: Import only what you need for optimal bundle size
• TypeScript Support: Full TypeScript definitions with modular exports
• React Hooks: Reusable hooks for common patterns
• HTTP Services: Configured HTTP client with error handling
• Constants & Utilities: Shared constants and utility functions

📦 Installation

npm install @pnkx-lib/core
# or
pnpm add @pnkx-lib/core

🚀 Usage

Individual Module Imports (Recommended for Tree Shaking)

// Import specific hooks (small bundle size)
import { useToggle } from '@pnkx-lib/core/hooks/useToggle';
import { useErrorHandler } from '@pnkx-lib/core/hooks/useErrorHandler';

// Import specific constants  
import { CategoryActionCode } from '@pnkx-lib/core/constants/bulkAction';
import { STORAGE_KEYS } from '@pnkx-lib/core/constants/storage';

// Import specific error constants
import { CommonErrorCodes } from '@pnkx-lib/core/constants/error/errorCodeConstants';
import { COMMON_ERROR_CODES, ALL_ERROR_CODES } from '@pnkx-lib/core/constants/error/errorCodes';

// Import specific services
import { httpService } from '@pnkx-lib/core/services/httpService';

// Import specific types
import type { InitialFiltersSearch, PaginationFilters } from '@pnkx-lib/core/interface/filters';

Bundle Index Imports (Less Optimal)

// Imports entire module - larger bundle size
import { useToggle } from '@pnkx-lib/core/hooks';
import { CategoryActionCode } from '@pnkx-lib/core/constants';

📊 Module Sizes (Tree Shaking Benefits)

| Module | Size | Description | |--------|------|-------------| | hooks/useToggle | 413 bytes | Simple toggle hook | | hooks/useErrorHandler | 2.43 KB | Error handling hook | | hooks/useHandleBulkAction | 2.03 KB | Bulk action handler | | constants/bulkAction | 1.77 KB | Action constants | | constants/storage | 111 bytes | Storage keys | | constants/error/errorCodeConstants | 6.67 KB | Error code constants | | constants/error/errorCodes | 18.89 KB | All error messages | | hooks/useFiltersHandler | 96.6 KB | Complex filter handler | | services/httpService | 98.2 KB | HTTP service with Axios |

🎯 Tree Shaking Benefit: Import only what you need! A simple app using just useToggle and CategoryActionCode will bundle only ~2.2KB instead of ~200KB.

🔧 Available Modules

Hooks

• useToggle - Simple boolean state toggle
• useErrorHandler - Global error handling
• useHandleBulkAction - Bulk operations handler
• useFiltersHandler - Complex filtering and pagination

Services

• httpService - Configured Axios instance
• errorHandlerService - Error handling service

Constants

• bulkAction - Action codes and messages
• storage - Storage keys
• statusConfig - Status configurations
• error - Error code constants

Utils

• bulkActionUtils - Bulk action utilities

Types/Interfaces

• filters - Filter and pagination types
• bulkAction - Bulk action types
• errorHandling - Error handling types

📖 Documentation

• Tree Shaking Guide - Detailed tree shaking optimization
• Bulk Action Refactor - Bulk action improvements

🧪 Testing Tree Shaking

# Test tree shaking
cd examples
node tree-shaking-test.js

🔧 Troubleshooting

Consumer Project Issues

If you're having issues in your project, you can use our troubleshooting script:

# Download and run troubleshooting script
curl -o troubleshoot.sh https://raw.githubusercontent.com/your-org/pnkx-ui/main/packages/core/scripts/troubleshoot-consumer.sh
chmod +x troubleshoot.sh
./troubleshoot.sh

Or copy the script from packages/core/scripts/troubleshoot-consumer.sh and run it in your project directory.

TypeScript Declaration Errors

If you encounter TypeScript errors like:

Could not find a declaration file for module '@pnkx-lib/core'

Solutions:

1. Update to latest version:

   npm install @pnkx-lib/core@latest

2. Clear cache and reinstall:

   rm -rf node_modules package-lock.json
   npm install

3. Check TypeScript configuration:

   // tsconfig.json
   {
     "compilerOptions": {
       "moduleResolution": "bundler", // or "node"
       "allowSyntheticDefaultImports": true,
       "esModuleInterop": true
     }
   }

4. Verify import paths:

   // ✅ Correct
   import { useToggle } from '@pnkx-lib/core/hooks/useToggle';
      
   // ❌ May cause issues in some setups
   import { useToggle } from '@pnkx-lib/core';

Bundle Size Issues

If your bundle is too large:

1. Use individual imports instead of index imports
2. Check which modules you're importing - some are large (useFiltersHandler: 96KB)
3. Use dynamic imports for heavy modules when possible

Performance Issues

1. Avoid importing unused modules
2. Use tree shaking verification tools
3. Monitor bundle analyzer output

Built with tree shaking optimization for minimal bundle impact 🚀

Expanding the ESLint configuration

If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:

export default tseslint.config({
  extends: [
    // Remove ...tseslint.configs.recommended and replace with this
    ...tseslint.configs.recommendedTypeChecked,
    // Alternatively, use this for stricter rules
    ...tseslint.configs.strictTypeChecked,
    // Optionally, add this for stylistic rules
    ...tseslint.configs.stylisticTypeChecked,
  ],
  languageOptions: {
    // other options...
    parserOptions: {
      project: ['./tsconfig.node.json', './tsconfig.app.json'],
      tsconfigRootDir: import.meta.dirname,
    },
  },
})

You can also install eslint-plugin-react-x and eslint-plugin-react-dom for React-specific lint rules:

// eslint.config.js
import reactX from 'eslint-plugin-react-x'
import reactDom from 'eslint-plugin-react-dom'

export default tseslint.config({
  plugins: {
    // Add the react-x and react-dom plugins
    'react-x': reactX,
    'react-dom': reactDom,
  },
  rules: {
    // other rules...
    // Enable its recommended typescript rules
    ...reactX.configs['recommended-typescript'].rules,
    ...reactDom.configs.recommended.rules,
  },
})

🔧 Troubleshooting

Consumer Project Issues

If you're having issues in your project, you can use our troubleshooting script:

# Download and run troubleshooting script
curl -o troubleshoot.sh https://raw.githubusercontent.com/your-org/pnkx-ui/main/packages/core/scripts/troubleshoot-consumer.sh
chmod +x troubleshoot.sh
./troubleshoot.sh

Or copy the script from packages/core/scripts/troubleshoot-consumer.sh and run it in your project directory.

TypeScript Declaration Errors

If you encounter TypeScript errors like:

Could not find a declaration file for module '@pnkx-lib/core'

Solutions:

1. Update to latest version:

   npm install @pnkx-lib/core@latest

2. Clear cache and reinstall:

   rm -rf node_modules package-lock.json
   npm install

3. Check TypeScript configuration:

   // tsconfig.json
   {
     "compilerOptions": {
       "moduleResolution": "bundler", // or "node"
       "allowSyntheticDefaultImports": true,
       "esModuleInterop": true
     }
   }

4. Verify import paths:

   // ✅ Correct
   import { useToggle } from '@pnkx-lib/core/hooks/useToggle';
      
   // ❌ May cause issues in some setups
   import { useToggle } from '@pnkx-lib/core';

Bundle Size Issues

If your bundle is too large:

1. Use individual imports instead of index imports
2. Check which modules you're importing - some are large (useFiltersHandler: 96KB)
3. Use dynamic imports for heavy modules when possible

Performance Issues

1. Avoid importing unused modules
2. Use tree shaking verification tools
3. Monitor bundle analyzer output

Built with tree shaking optimization for minimal bundle impact 🚀