CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-strapi--helper-plugin

Helper library for Strapi plugins development providing React components, hooks, utilities, and TypeScript types for building plugin interfaces

—

Pending
Overview
Eval results
Files

features.mddocs/

Features

The @strapi/helper-plugin package provides 10 feature contexts and hooks that manage core application functionality including app information, notifications, permissions, tracking, and plugin extensibility. These features provide the foundation for building integrated Strapi plugins.

App Information

Context and hook for accessing Strapi application metadata and environment information.

// App information context
interface AppInfoContextValue {
  autoReload?: boolean;
  communityEdition?: boolean;
  currentEnvironment?: string;
  dependencies?: Record<string, string>;
  latestStrapiReleaseTag?: string;
  nodeVersion?: string;
  projectId?: string | null;
  setUserDisplayName: (name: string) => void;
  shouldUpdateStrapi: boolean;
  strapiVersion?: string | null;
  useYarn?: boolean;
  userDisplayName: string;
  userId?: string;
}

// Hook for app information
function useAppInfo(): AppInfoContextValue | {};

// Provider component
interface AppInfoProviderProps extends AppInfoContextValue {
  children: React.ReactNode;
}
function AppInfoProvider(props: AppInfoProviderProps): JSX.Element;

// React context instance
const AppInfoContext: React.Context<AppInfoContextValue | {}>;

Usage Examples:

// Access app information
const {
  strapiVersion,
  shouldUpdateStrapi,
  currentEnvironment,
  setUserDisplayName
} = useAppInfo();

// Display version information
if (shouldUpdateStrapi) {
  // Show update notification
}

// Update user display name
const handleNameChange = (newName: string) => {
  setUserDisplayName(newName);
};

Auto-Reload Overlay Blocker

Context and hook for managing auto-reload blocking during critical operations.

// Auto-reload overlay blocker hook
interface AutoReloadOverlayBlockerReturn {
  lockAppWithAutoreload?: () => void;
  unlockAppWithAutoreload?: () => void;
}

function useAutoReloadOverlayBlocker(): AutoReloadOverlayBlockerReturn;

// Provider component
interface AutoReloadOverlayBlockerProviderProps {
  children: React.ReactNode;
}
function AutoReloadOverlayBlockerProvider(props: AutoReloadOverlayBlockerProviderProps): JSX.Element;

Usage Examples:

// Block auto-reload during operations
const { lockAppWithAutoreload, unlockAppWithAutoreload } = useAutoReloadOverlayBlocker();

const handleCriticalOperation = async () => {
  lockAppWithAutoreload?.();
  try {
    await performCriticalOperation();
  } finally {
    unlockAppWithAutoreload?.();
  }
};

Custom Fields

Context and hook for managing custom field registry and components.

// Custom fields hook
interface CustomFieldsReturn {
  get: (uid: string) => CustomFieldServerSide | undefined;
}

function useCustomFields(): CustomFieldsReturn;

// Provider component
interface CustomFieldsProviderProps {
  children: React.ReactNode;
  customFields?: Record<string, CustomFieldServerSide>;
}
function CustomFieldsProvider(props: CustomFieldsProviderProps): JSX.Element;

// Custom field interface
interface CustomFieldServerSide {
  name: string;
  pluginId?: string;
  type: string;
  icon?: React.ComponentType;
  intlLabel: {
    id: string;
    defaultMessage: string;
  };
  intlDescription: {
    id: string;
    defaultMessage: string;
  };
  components: {
    Input: React.ComponentType<any>;
  };
  options?: {
    base?: Array<{
      sectionTitle: { id: string; defaultMessage: string } | null;
      items: Array<{
        intlLabel: { id: string; defaultMessage: string };
        name: string;
        type: string;
        value?: any;
      }>;
    }>;
    advanced?: Array<{
      sectionTitle: { id: string; defaultMessage: string } | null;
      items: Array<{
        intlLabel: { id: string; defaultMessage: string };
        name: string;
        type: string;
        value?: any;
      }>;
    }>;
    validator?: (args: any) => any;
  };
}

Usage Examples:

// Access custom fields registry
const { get } = useCustomFields();

const customField = get('plugin::my-plugin.color-picker');

if (customField) {
  const { Input } = customField.components;
  // Render custom field component
}

Guided Tour

Context and hook for managing guided tour state and navigation.

// Guided tour context
interface GuidedTourContextValue {
  currentStep: GuidedTourStep | null;
  guidedTourState: {
    contentTypeBuilder: {
      create: boolean;
      success: boolean;
    };
    contentManager: {
      create: boolean;
      success: boolean;
    };
    apiTokens: {
      create: boolean;
      success: boolean;
    };
    transferTokens: {
      create: boolean;
      success: boolean;
    };
  };
  isGuidedTourVisible: boolean;
  isSkipped: boolean;
  setCurrentStep: (step: GuidedTourStep | null) => void;
  setGuidedTourVisibility: (isVisible: boolean) => void;
  setSkipped: (isSkipped: boolean) => void;
  setStepState: (step: GuidedTourStep, state: boolean) => void;
  startSection: (section: GuidedTourSectionKey) => void;
}

// Hook for guided tour
function useGuidedTour(): GuidedTourContextValue;

// Provider component
interface GuidedTourProviderProps extends GuidedTourContextValue {
  children: React.ReactNode;
}
function GuidedTourProvider(props: GuidedTourProviderProps): JSX.Element;

// Step types
type GuidedTourStep = `${GuidedTourSectionKey}.${GuidedTourStepKey}`;
type GuidedTourSectionKey = 'contentTypeBuilder' | 'contentManager' | 'apiTokens' | 'transferTokens';
type GuidedTourStepKey = 'create' | 'success';

Usage Examples:

// Access guided tour state
const {
  currentStep,
  isGuidedTourVisible,
  setCurrentStep,
  setStepState,
  startSection
} = useGuidedTour();

// Start a guided tour section
const handleStartTour = () => {
  startSection('contentTypeBuilder');
  setCurrentStep('contentTypeBuilder.create');
};

// Complete a tour step
const handleStepComplete = () => {
  setStepState('contentTypeBuilder.create', true);
  setCurrentStep('contentTypeBuilder.success');
};

Library

Context and hook for managing component library and registry.

// Library hook
interface LibraryFields {
  [key: string]: React.ComponentType<any>;
}

interface LibraryReturn {
  fields: LibraryFields;
}

function useLibrary(): LibraryReturn;

// Provider component
interface LibraryProviderProps {
  children: React.ReactNode;
  fields?: LibraryFields;
}
function LibraryProvider(props: LibraryProviderProps): JSX.Element;

Usage Examples:

// Access registered components
const { fields } = useLibrary();

const CustomInput = fields['my-custom-input'];

if (CustomInput) {
  return <CustomInput {...props} />;
}

Notifications

Context and hooks for displaying toast notifications to users.

// Notification configuration
interface NotificationConfig {
  blockTransition?: boolean;
  link?: NotificationLink;
  message?: string | TranslationMessage;
  onClose?: () => void;
  timeout?: number;
  title?: string | TranslationMessage;
  type?: 'info' | 'warning' | 'softWarning' | 'success';
}

// Notification link
interface NotificationLink {
  label: string | MessageDescriptor;
  target?: string;
  url: string;
}

// Hook for notifications
function useNotification(): (config: NotificationConfig) => void;

// Provider component
interface NotificationsProviderProps {
  children: React.ReactNode;
}
function NotificationsProvider(props: NotificationsProviderProps): JSX.Element;

// Context value
interface NotificationsContextValue {
  toggleNotification: (config: NotificationConfig) => void;
}
const NotificationsContext: React.Context<NotificationsContextValue>;

Usage Examples:

// Display notifications
const toggleNotification = useNotification();

// Success notification
toggleNotification({
  type: 'success',
  message: 'Data saved successfully!'
});

// Error notification with link
toggleNotification({
  type: 'warning',
  message: 'Failed to save data',
  link: {
    label: 'View documentation',
    url: '/docs/troubleshooting'
  },
  timeout: 5000
});

// Custom notification with callback
toggleNotification({
  type: 'info',
  message: 'Processing...',
  blockTransition: true,
  onClose: () => {
    console.log('Notification closed');
  }
});

Overlay Blocker

Context and hook for managing overlay blocking during operations.

// Overlay blocker hook
interface OverlayBlockerReturn {
  lockApp?: () => void;
  unlockApp?: () => void;
}

function useOverlayBlocker(): OverlayBlockerReturn;

// Provider component
interface OverlayBlockerProviderProps {
  children: React.ReactNode;
}
function OverlayBlockerProvider(props: OverlayBlockerProviderProps): JSX.Element;

Usage Examples:

// Block UI during operations
const { lockApp, unlockApp } = useOverlayBlocker();

const handleLongOperation = async () => {
  lockApp?.();
  try {
    await performLongOperation();
  } finally {
    unlockApp?.();
  }
};

RBAC (Role-Based Access Control)

Context and hook for managing user permissions and role-based access.

// Permission interface
interface Permission {
  id?: Entity.ID;
  action: string;
  actionParameters?: object;
  subject?: string | null;
  properties?: {
    fields?: string[];
    locales?: string[];
    [key: string]: any;
  };
  conditions?: string[];
}

// RBAC context value
interface RBACContextValue {
  allPermissions: Permission[];
  refetchPermissions: () => void;
}

// Hook for RBAC
function useRBAC(): RBACContextValue;
function useRBACProvider(): RBACContextValue; // Alias

// Context instance
const RBACContext: React.Context<RBACContextValue>;

Usage Examples:

// Access user permissions
const { allPermissions, refetchPermissions } = useRBAC();

// Check specific permissions
const canCreate = allPermissions.some(
  permission => permission.action === 'create' && permission.subject === 'api::article.article'
);

// Refresh permissions after role changes
const handleRoleUpdate = async () => {
  await updateUserRole();
  refetchPermissions();
};

Strapi App

Context and hook for managing core Strapi application state and functionality.

// Strapi app hook
interface StrapiAppReturn {
  // Core app functionality (implementation varies)
  [key: string]: any;
}

function useStrapiApp(): StrapiAppReturn;

// Provider component
interface StrapiAppProviderProps {
  children: React.ReactNode;
}
function StrapiAppProvider(props: StrapiAppProviderProps): JSX.Element;

Usage Examples:

// Access Strapi app context
const strapiApp = useStrapiApp();

// Use app-level functionality
// (specific APIs depend on implementation)

Tracking

Context and hook for analytics and event tracking.

// Telemetry properties
interface TelemetryProperties {
  useTypescriptOnServer?: boolean;
  useTypescriptOnAdmin?: boolean;
  isHostedOnStrapiCloud?: boolean;
  numberOfAllContentTypes?: number;
  numberOfComponents?: number;
  numberOfDynamicZones?: number;
}

// Tracking context value
interface TrackingContextValue {
  uuid?: string | boolean;
  deviceId?: string;
  telemetryProperties?: TelemetryProperties;
}

// Tracking hook return
interface UseTrackingReturn {
  trackUsage<TEvent extends TrackingEvent>(
    event: TEvent['name'],
    properties?: TEvent['properties']
  ): Promise<null | AxiosResponse<string>>;
}

// Hook for tracking
function useTracking(): UseTrackingReturn;

// Provider component
interface TrackingProviderProps {
  children: React.ReactNode;
  value?: TrackingContextValue;
}
function TrackingProvider(props: TrackingProviderProps): JSX.Element;

// Event types (extensive list of predefined events)
type TrackingEvent = EventWithoutProperties | EventsWithProperties;

Usage Examples:

// Track user events
const { trackUsage } = useTracking();

// Track simple events
trackUsage('didCreateEntry');

// Track events with properties
trackUsage('didFilterEntries', {
  useRelation: true
});

// Track navigation events
trackUsage('willNavigate', {
  from: '/admin/plugins',
  to: '/admin/content-manager'
});

// Track content operations
trackUsage('didEditEntry', {
  status: 'draft',
  error: null
});

Integration Patterns

Feature Composition

// Combine multiple features in a plugin
const MyPlugin = () => {
  const { trackUsage } = useTracking();
  const toggleNotification = useNotification();
  const { canCreate } = useRBAC();
  const { lockApp, unlockApp } = useOverlayBlocker();
  
  const handleCreateAction = async () => {
    if (!canCreate) {
      toggleNotification({
        type: 'warning',
        message: 'You do not have permission to create entries'
      });
      return;
    }
    
    trackUsage('willCreateEntry');
    lockApp();
    
    try {
      await createEntry();
      trackUsage('didCreateEntry', { status: 'success' });
      toggleNotification({
        type: 'success',
        message: 'Entry created successfully'
      });
    } catch (error) {
      trackUsage('didCreateEntry', { status: 'error', error });
      toggleNotification({
        type: 'warning',
        message: 'Failed to create entry'
      });
    } finally {
      unlockApp();
    }
  };
  
  return (
    <Button onClick={handleCreateAction}>
      Create Entry
    </Button>
  );
};

Provider Setup

// Set up multiple feature providers
const App = () => {
  return (
    <AppInfoProvider {...appInfoProps}>
      <NotificationsProvider>
        <TrackingProvider value={trackingConfig}>
          <OverlayBlockerProvider>
            <GuidedTourProvider {...tourProps}>
              <MyApplication />
            </GuidedTourProvider>
          </OverlayBlockerProvider>
        </TrackingProvider>
      </NotificationsProvider>
    </AppInfoProvider>
  );
};

Custom Feature Integration

// Create custom hook that combines features
const useAppFeatures = () => {
  const appInfo = useAppInfo();
  const { trackUsage } = useTracking();
  const toggleNotification = useNotification();
  
  const reportError = useCallback((error: Error) => {
    trackUsage('didEncounterError', { error: error.message });
    toggleNotification({
      type: 'warning',
      message: 'An error occurred. Please try again.',
      timeout: 5000
    });
  }, [trackUsage, toggleNotification]);
  
  return {
    ...appInfo,
    trackUsage,
    reportError
  };
};

Context Architecture

The feature contexts follow a consistent pattern:

  1. Context Definition: React context with typed interface
  2. Provider Component: Manages context state and provides value
  3. Hook: Convenient access to context value
  4. Type Safety: Full TypeScript support with proper interfaces

This architecture ensures:

  • Consistent APIs across all features
  • Type Safety for all context values and operations
  • Performance Optimization through memoized values
  • Easy Integration between different features
  • Extensibility for custom plugin functionality

Install with Tessl CLI

npx tessl i tessl/npm-strapi--helper-plugin

docs

content-manager.md

features.md

hooks.md

index.md

types.md

ui-components.md

utilities.md

tile.json