Why this package exists

Integrating dynamic prompts into React applications often involves managing complex state, handling loading states during LLM calls, and syncing context data (like user profiles or current page state) into prompts.

@promptforgee/react bridges the gap between @promptforgee/core and React. It will provide specialized hooks to build, update, and validate prompts responsively, along with headless UI components for prompt debugging and visualization.

[!WARNING]
This package is currently in early development. The APIs described below are planned features.

Features

• 🚧 usePrompt() Hook: Reactively build prompts based on component state.
• 🚧 Context Syncing: Automatically inject React Context values into your prompts.
• 🚧 Headless UI Components: Render prompt diagnostic reports directly in your app.
• 🚧 Suspense Support: Seamless integration with React Suspense for LLM streaming states.

Installation

# npm
npm install @promptforgee/react

# pnpm
pnpm add @promptforgee/react

# yarn
yarn add @promptforgee/react

# bun
bun add @promptforgee/react

Quick Start

import { hello } from '@promptforgee/react';

// Currently exports a placeholder testing function.
console.log(hello());
// Outputs: "Hello from @promptforgee/react"

API Overview

Current API

| Export | Description | | --------- | ------------------------------------------------ | | hello() | A placeholder function ensuring package linking. |

🚧 Planned API

| Export | Description | | ---------------------------- | --------------------------------------------------------------------- | | 🚧 usePrompt(initialState) | Hook to manage a Prompt builder instance with React state. | | 🚧 PromptProvider | React Context provider to share base contexts globally. | | 🚧 PromptDebugger | A headless component that renders an @promptforgee/analyzer report. |

Real-world Example (🚧 Planned)

The following code demonstrates how we envision this package being used in the future:

import { usePrompt } from '@promptforgee/react';
import { useUser } from './hooks/useUser';

export function EmailGenerator() {
  const { user } = useUser();
  const [topic, setTopic] = useState('');

  // 🚧 Planned hook usage
  const prompt = usePrompt()
    .role('Assistant')
    .task(`Write an email about: ${topic}`)
    .context(`User Name: ${user.name}`);

  const handleGenerate = async () => {
    const promptString = prompt.build();
    // await runLLM(promptString)...
  };

  return (
    <div>
      <input value={topic} onChange={(e) => setTopic(e.target.value)} />
      <button onClick={handleGenerate}>Generate</button>
    </div>
  );
}

Ecosystem

@promptforgee/react will serve as the presentation layer for PromptForge.

@promptforgee/core (Builds the underlying prompt) ↓ @promptforgee/react (You are here)

Documentation

For full documentation and advanced usage, visit promptforge.dev/docs/react.

Examples

Check out our Examples directory for more real-world use cases.

Roadmap

• 🚧 Implement usePrompt with deep state equality checks.
• 🚧 Create the <PromptDebugger /> component.
• 🚧 Add Next.js App Router specific hooks (useServerPrompt).

Contributing

We welcome contributions! Please read our Contributing Guide to get started.

License

MIT © Omnikon-Org