Generated banner for Vercel Composition Patterns
Generated logo for Vercel Composition Patterns

Vercel Composition Patterns

JetBrainsOfficialCreated by VercelDistributed by JetBrains

  • Skill
  • Guidelines
  • Software development
  • MIT
  • No issues found

From the author

React composition patterns that scale. Use when refactoring components with boolean prop proliferation, building flexible component libraries, or designing reusable APIs. Triggers on tasks involving compound components, render props, context providers, or component architecture. Includes React 19 API changes.
— the description by Vercel

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured set of guidelines for designing flexible, maintainable React components. It focuses on replacing complex boolean prop configurations with robust composition patterns such as compound components, context providers, and explicit variants. The guide is designed to help developers and AI agents create cleaner, more scalable component APIs, including specific considerations for React 19 API updates.

What it does

  • Provides architectural patterns to eliminate boolean prop proliferation.
  • Defines best practices for compound components and shared context usage.
  • Offers guidance on state management and decoupling implementation details.
  • Includes specific rules for leveraging modern React 19 APIs.
  • Encourages the use of children over render props for better composition.
  • Standardizes component API design for improved maintainability.

When to use it

  • When refactoring components that have become difficult to manage due to excessive boolean props.
  • During the design phase of a reusable component library.
  • When evaluating or reviewing existing component architecture for scalability.
  • When implementing complex state sharing between sibling components.
  • When upgrading or building new features using React 19.

Advantages

  • Reduces technical debt caused by complex, hard-to-maintain component APIs.
  • Improves code readability for both human developers and AI agents.
  • Promotes a consistent architectural style across the codebase.
  • Ensures component designs are flexible and easier to extend over time.

Usage examples

“How can I refactor a button component that has too many boolean props like 'isPrimary', 'isLarge', and 'isDisabled'?”
The agent will suggest using explicit variant components or a composition-based approach to replace boolean flags with more descriptive, scalable patterns.
“What is the recommended way to share state between complex compound components in React 19?”
The agent will provide guidance on using context providers and the latest React 19 APIs to decouple state management from the component structure.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/jetbrains/vercel-composition-patterns/download
  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip vercel-composition-patterns.zip -d .agents/skills

Documentation by Vercel

React Composition Patterns

Composition patterns for building flexible, maintainable React components. Avoid boolean prop proliferation by using compound components, lifting state, and composing internals. These patterns make codebases easier for both humans and AI agents to work with as they scale.

When to Apply

Reference these guidelines when:

  • Refactoring components with many boolean props

  • Building reusable component libraries

  • Designing flexible component APIs

  • Reviewing component architecture

  • Working with compound components or context providers

Rule Categories by Priority

PriorityCategoryImpactPrefix
1Component ArchitectureHIGHarchitecture-
2State ManagementMEDIUMstate-
3Implementation PatternsMEDIUMpatterns-
4React 19 APIsMEDIUMreact19-

Quick Reference

1. Component Architecture (HIGH)
  • architecture-avoid-boolean-props - Don't add boolean props to customize behavior; use composition

  • architecture-compound-components - Structure complex components with shared context

2. State Management (MEDIUM)
  • state-decouple-implementation - Provider is the only place that knows how state is managed

  • state-context-interface - Define generic interface with state, actions, meta for dependency injection

  • state-lift-state - Move state into provider components for sibling access

3. Implementation Patterns (MEDIUM)
  • patterns-explicit-variants - Create explicit variant components instead of boolean modes

  • patterns-children-over-render-props - Use children for composition instead of renderX props

4. React 19 APIs (MEDIUM)

⚠️ React 19+ only. Skip this section if using React 18 or earlier.

  • react19-no-forwardref - Don't use forwardRef; use use() instead of useContext()

How to Use

Read individual rule files for detailed explanations and code examples:

rules/architecture-avoid-boolean-props.md
rules/state-context-interface.md

Each rule file contains:

  • Brief explanation of why it matters

  • Incorrect code example with explanation

  • Correct code example with explanation

  • Additional context and references

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md

Files

rules/state-context-interface.md


title: Define Generic Context Interfaces for Dependency Injection impact: HIGH impactDescription: enables dependency-injectable state across use-cases tags: composition, context, state, typescript, dependency-injection

Define Generic Context Interfaces for Dependency Injection

Define a generic interface for your component context with three parts: state, actions, and meta. This interface is a contract that any provider can implement—enabling the same UI components to work with completely different state implementations.

Core principle: Lift state, compose internals, make state dependency-injectable.

Incorrect (UI coupled to specific state implementation):

function ComposerInput() {
  // Tightly coupled to a specific hook
  const { input, setInput } = useChannelComposerState()
  return <TextInput value={input} onChangeText={setInput} />
}

Correct (generic interface enables dependency injection):

// Define a GENERIC interface that any provider can implement
interface ComposerState {
  input: string
  attachments: Attachment[]
  isSubmitting: boolean
}

interface ComposerActions {
  update: (updater: (state: ComposerState) => ComposerState) => void
  submit: () => void
}

interface ComposerMeta {
  inputRef: React.RefObject<TextInput>
}

interface ComposerContextValue {
  state: ComposerState
  actions: ComposerActions
  meta: ComposerMeta
}

const ComposerContext = createContext<ComposerContextValue | null>(null)

UI components consume the interface, not the implementation:

function ComposerInput() {
  const {
    state,
    actions: { update },
    meta,
  } = use(ComposerContext)

  // This component works with ANY provider that implements the interface
  return (
    <TextInput
      ref={meta.inputRef}
      value={state.input}
      onChangeText={(text) => update((s) => ({ ...s, input: text }))}
    />
  )
}

Different providers implement the same interface:

// Provider A: Local state for ephemeral forms
function ForwardMessageProvider({ children }: { children: React.ReactNode }) {
  const [state, setState] = useState(initialState)
  const inputRef = useRef(null)
  const submit = useForwardMessage()

  return (
    <ComposerContext
      value={{
        state,
        actions: { update: setState, submit },
        meta: { inputRef },
      }}
    >
      {children}
    </ComposerContext>
  )
}

// Provider B: Global synced state for channels
function ChannelProvider({ channelId, children }: Props) {
  const { state, update, submit } = useGlobalChannel(channelId)
  const inputRef = useRef(null)

  return (
    <ComposerContext
      value={{
        state,
        actions: { update, submit },
        meta: { inputRef },
      }}
    >
      {children}
    </ComposerContext>
  )
}

The same composed UI works with both:

// Works with ForwardMessageProvider (local state)
<ForwardMessageProvider>
  <Composer.Frame>
    <Composer.Input />
    <Composer.Submit />
  </Composer.Frame>
</ForwardMessageProvider>

// Works with ChannelProvider (global synced state)
<ChannelProvider channelId="abc">
  <Composer.Frame>
    <Composer.Input />
    <Composer.Submit />
  </Composer.Frame>
</ChannelProvider>

Custom UI outside the component can access state and actions:

The provider boundary is what matters—not the visual nesting. Components that need shared state don't have to be inside the Composer.Frame. They just need to be within the provider.

function ForwardMessageDialog() {
  return (
    <ForwardMessageProvider>
      <Dialog>
        {/* The composer UI */}
        <Composer.Frame>
          <Composer.Input placeholder="Add a message, if you'd like." />
          <Composer.Footer>
            <Composer.Formatting />
            <Composer.Emojis />
          </Composer.Footer>
        </Composer.Frame>

        {/* Custom UI OUTSIDE the composer, but INSIDE the provider */}
        <MessagePreview />

        {/* Actions at the bottom of the dialog */}
        <DialogActions>
          <CancelButton />
          <ForwardButton />
        </DialogActions>
      </Dialog>
    </ForwardMessageProvider>
  )
}

// This button lives OUTSIDE Composer.Frame but can still submit based on its context!
function ForwardButton() {
  const {
    actions: { submit },
  } = use(ComposerContext)
  return <Button onPress={submit}>Forward</Button>
}

// This preview lives OUTSIDE Composer.Frame but can read composer's state!
function MessagePreview() {
  const { state } = use(ComposerContext)
  return <Preview message={state.input} attachments={state.attachments} />
}

The ForwardButton and MessagePreview are not visually inside the composer box, but they can still access its state and actions. This is the power of lifting state into providers.

The UI is reusable bits you compose together. The state is dependency-injected by the provider. Swap the provider, keep the UI.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
Vercel
Publisher
JetBrains (Official)
Distributed by
JetBrains
Source
JetBrains/skills · composition-patterns · commit 3f53782
Licence
MIT License (redistribution allowed)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Vercel or JetBrains.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download vercel-composition-patterns.zip