Experience Card Utils

A collection of common ReactJS utility functions, hooks, and components for Experience Card development.

Installation

npm install experience-card-utils

Features

• 🎣 Custom Hooks: Reusable React hooks for common patterns
• 🛠️ Utility Functions: Helper functions for everyday tasks
• 🎨 Components: Pre-built React components for Experience Cards
• 🔌 Experience API: Functions for Ellucian Experience API integration

Usage

Experience API Functions

ExecuteServerlessAPI

Call Ellucian Integrate APIs with OAuth authentication:

import { ExecuteServerlessAPI } from 'experience-card-utils';

const response = await ExecuteServerlessAPI({
  pipelineApiName: 'xcgslist-update',
  cardId: 'A20136987',
  userInfo: { tenantAlias: 'your-tenant' },
  dataJsonString: JSON.stringify({ key: 'value' }),
  method: 'POST'
});

const result = JSON.parse(response);
console.log(result.data);

ExecuteServerlessAPIBatch

Process multiple items with concurrent batch processing:

import { ExecuteServerlessAPIBatch } from 'experience-card-utils';

const responses = await ExecuteServerlessAPIBatch({
  dataArray: [{ id: 1 }, { id: 2 }, { id: 3 }],
  pipelineApiName: 'xcgslist-update',
  cardId: 'A20136987',
  userInfo: { tenantAlias: 'your-tenant' },
  concurrentThreads: 3,
  onProgress: (results) => {
    console.log(`Progress: ${results.length} items processed`);
  }
});

fetchOauth

Get OAuth token from Experience API:

import { fetchOauth } from 'experience-card-utils';

const token = await fetchOauth({
  userInfo: { tenantAlias: 'your-tenant' }
});

Hooks

useDebounce

Debounce a value to optimize performance:

import { useDebounce } from 'experience-card-utils';

function SearchComponent() {
  const [searchTerm, setSearchTerm] = useState('');
  const debouncedSearch = useDebounce(searchTerm, 500);

  // Use debouncedSearch for API calls
}

useLocalStorage

Persist state in localStorage:

import { useLocalStorage } from 'experience-card-utils';

function App() {
  const [name, setName] = useLocalStorage('username', 'Guest');
  // State automatically syncs with localStorage
}

Utilities

classNames

Conditionally combine CSS classes:

import { classNames } from 'experience-card-utils';

const buttonClass = classNames(
  'btn',
  { 'btn-active': isActive },
  disabled && 'btn-disabled'
);

formatDate

Format dates consistently:

import { formatDate } from 'experience-card-utils';

const formatted = formatDate(new Date(), { 
  year: 'numeric', 
  month: 'short', 
  day: 'numeric' 
});

Components

Card

A reusable card component:

import { Card } from 'experience-card-utils';

function App() {
  return (
    <Card title="My Card" onClick={() => console.log('Clicked!')}>
      <p>Card content goes here</p>
    </Card>
  );
}

Development

Build

npm run build

Watch Mode

npm run dev

Type Check

npm run type-check

Lint

npm run lint

Testing Locally Before Publishing

Option 1: Using npm link (Recommended for Development)

1. In this library project:

npm run build
npm link

2. In your Experience Card project:

npm link experience-card-utils

3. Import and use:

import { ExecuteServerlessAPI, useDebounce } from '@experience/card-utils';

4. To unlink later:

# In your Experience Card project
npm unlink experience-card-utils

# In this library project
npm unlink

Option 2: Using npm pack (Test Production Build)

1. Build and create tarball:

npm run build
npm pack

This creates a file like experience-card-utils-1.0.0.tgz

2. In your Experience Card project, install the local package:

npm install /path/to/plugins/experience-card-utils-1.0.0.tgz

3. Import and use normally:

import { ExecuteServerlessAPI } from '@experience/card-utils';

Publishing to npm

First Time Setup

1. Create an npm account at https://www.npmjs.com/signup

2. Login via terminal:

npm login

Publishing Steps

1. Update version in package.json (follow semantic versioning):

{
  "version": "1.0.1"  // or 1.1.0, 2.0.0, etc.
}

2. Build and publish:

npm run build
npm publish

The package is configured for public access on npmjs.

Version Updates

• Patch (1.0.0 → 1.0.1): Bug fixes

  npm version patch
  npm publish

• Minor (1.0.0 → 1.1.0): New features, backward compatible

  npm version minor
  npm publish

• Major (1.0.0 → 2.0.0): Breaking changes

  npm version major
  npm publish

Using in Experience Card Projects

Installation

npm install @experience/card-utils

TypeScript Support

The package includes TypeScript definitions automatically. No additional @types package needed.

Import Examples

// Import specific functions
import { ExecuteServerlessAPI, useDebounce, Card } from 'experience-card-utils';

// Or import types
import type { ExecuteServerlessAPIParams } from 'experience-card-utils';

React Peer Dependencies

This library requires React 16.8+ (hooks support). Make sure your Experience Card project has:

• react ^16.8.0 || ^17.0.0 || ^18.0.0
• react-dom ^16.8.0 || ^17.0.0 || ^18.0.0

Package Details

• Package Name: experience-card-utils
• Formats: ESM and CommonJS
• TypeScript: Full type definitions included
• Tree-shakeable: Import only what you need
• Side-effect free: Safe for bundler optimization

License

MIT