Add Components

Directory Structure

StarForge components must follow a specific structure:

src/
├── components/
│   ├── star-forge/          # StarForge Components
│   │   ├── inputs/          # Input components
│   │   ├── alerts/          # Alert components
│   │   ├── heros/           # Hero components
│   │   ├── footer/          # Footer components
│   │   └── ...              # Other components
│   └── ui/                  # Base shadcn/ui components
├── hooks/
│   └── star-forge/          # Custom StarForge hooks
└── lib/
    └── utils.ts             # Shared utilities

Step by Step to Create a Component

Create the Component File

Create your component in the appropriate directory within src/components/star-forge/:

// src/components/star-forge/my-component.tsx
'use client';

import { useState } from 'react';
import { cn } from '@/lib/utils';

export interface MyComponentProps {
  // Define your props here
  children?: React.ReactNode;
  className?: string;
  variant?: 'default' | 'secondary';
}

export function MyComponent({
  children,
  className,
  variant = 'default'
}: MyComponentProps) {
  return (
    <div
      className={cn(
        'base-component-styles',
        variant === 'secondary' && 'secondary-styles',
        className
      )}
    >
      {children}
    </div>
  );
}

export default MyComponent;

Create Hooks (if necessary)

If your component needs custom hooks, create them in src/hooks/star-forge/:

// src/hooks/star-forge/use-my-hook.ts
import { useState, useEffect } from 'react';

export function useMyHook(initialValue: string) {
  const [value, setValue] = useState(initialValue);

  // Your hook logic here

  return { value, setValue };
}

Add to Registry.json

Add your component to the registry.json in the project root:

{
  "name": "my-component",
  "type": "registry:ui",
  "dependencies": ["lucide-react"], // External dependencies
  "registryDependencies": ["button"], // Dependencies on other shadcn components
  "files": [
    {
      "path": "src/components/star-forge/my-component.tsx",
      "type": "registry:ui"
    },
    {
      "path": "src/hooks/star-forge/use-my-hook.ts",
      "type": "registry:hook"
    }
  ]
}

Type Options

registry:ui - Use for UI components (React components, visual elements)
registry:hook - Use for custom React hooks
registry:lib - Use for utility functions, constants, or helper libraries
registry:component - Use for complete component packages with multiple files

Install Dependencies

If your component uses external dependencies, install them:

npm install lucide-react
# or
yarn add lucide-react
# or
pnpm add lucide-react

Create MDX Documentation

Create an MDX file to document your component in content/docs/components/:

---
title: Section
description: Component for organizing sections
---

import { ComponentPreview } from '@/components/common/preview/component-preview';
import { extractSourceCode } from '@/lib/code';

## Section

<ComponentPreview
  name="my-component"
  classNameComponentContainer="min-h-[600px]"
  code={(await extractSourceCode('my-component')).code}
  sourceCode={(await extractSourceCode('my-component')).sourceCode}
  lang="tsx"
/>

### or use DrawerCodePreview

<DrawerCodePreview
  name="my-component"
  classNameComponentContainer="p-20"
  code={(await extractSourceCode('my-component')).code}
  lang="tsx"
/>

Basic Usage

<Badge>Default Badge</Badge>

Variants

Default

<Badge>Default</Badge>

Secondary

<Badge variant="secondary">Secondary</Badge>

Destructive

<Badge variant="destructive">Destructive</Badge>

Outline

<Badge variant="outline">Outline</Badge>

Props

Prop	Type	Default	Description
variant	`'default' \| 'secondary' \| 'destructive' \| 'outline'`	`'default'`	Visual variant of the badge
className	`string`	-	Additional CSS classes
children	`React.ReactNode`	-	Badge content

6. Build the Registry

Run the shadcn build to update the registry:

npx shadcn@latest build

Naming Conventions

Components

Use kebab-case for file names: my-component.tsx
Use PascalCase for component names: MyComponent
Follow the category-name pattern when applicable: hero-1, alert-1, search-1

Hooks

Use kebab-case for file names: use-my-hook.ts
Use camelCase for hook names: useMyHook

Structure by Category

Inputs: Form and input components
Alerts: Alert and notification components
Heros: Hero/main section components
Footer: Footer components
Cards: Card components
Backgrounds: Background components

Best Practices

Always use 'use client' for components that use React hooks
Export interfaces for TypeScript
Use cn() to combine classes
Document props with TypeScript
Follow variant pattern when applicable
Test components before adding to registry
Use minimal dependencies - only what's necessary

Validation

After adding your component:

Check if TypeScript compiles:
```
npm run type-check
```
Test the component locally:
```
npm run dev
```
Check the build:
```
npm run build
```
Test the registry:
```
npx shadcn@latest add badge-1
```

Next Steps

Create documentation for your component
Add usage examples

Reusing Existing Libraries

Before creating a new component, check if you can reuse the libraries and components already existing in the project. This helps maintain consistency and reduce bundle size.

Available Libraries

The project already includes several libraries that can be used:

shadcn/ui: Ready-to-use base UI components
Lucide React: Various icons for interfaces
class-variance-authority: For managing component variants
Tailwind CSS: For styling
Framer Motion: For animations

Checking Existing Components

Before creating, explore:

shadcn/ui components in src/components/ui/
StarForge components in src/components/star-forge/
Custom hooks in src/hooks/star-forge/

Benefits of Reuse

Less code: Reduces the amount of code to maintain
Consistency: Maintains uniform design and behavior
Performance: Avoids dependency duplication
Maintainability: Fewer components to maintain and update

Questions?

If you have questions about how to add components, consult the existing examples in the project or open an issue in the repository.