CONTRIBUTING.md

Contributing to MagicUI

Thank you for your interest in contributing to MagicUI! We appreciate your support and look forward to your contributions. This guide will help you understand the directory structure and provide detailed instructions on how to add a new component to MagicUI.

Read the example PR to learn which files you need to add. You only need to change 5 files to add a new component or effect and it only takes around 10 minutes of work!

Once done, open a pull request from your forked repo to the main repo here.

Getting Started

Fork and Clone the Repository

1. Fork this repository
   Click here to fork the repository.

2. Clone your forked repository to your local machine

   git clone https://github.com/<YOUR_USERNAME>/magicui.git

3. Navigate to the project directory

   cd magicui

4. Create a new branch for your changes

   git checkout -b my-new-branch

5. Install dependencies

   pnpm i

6. Create a .env.local file

   touch .env.local && echo "NEXT_PUBLIC_APP_URL=http://localhost:3000" > .env.local

7. Run the project

   pnpm dev

Adding a New Component

To add a new component to MagicUI, you will need to modify several files. Follow these steps:

1. Create Component

Create the main component in registry/default/magicui/example-component.tsx

import React from 'react'

export default function ExampleComponent() {
  return (
    <div>
      This is your component.
    </div>
  )
}

2. Create Component Demo

Provide a basic example to showcase your component in registry/default/example/example-component-demo.tsx

import ExampleComponent from '@/registry/default/magicui/example-component'

export default function ExampleComponentDemo() {
  return (
    <div className="relative justify-center">
      <ExampleComponent />
    </div>
  )
}

3. Update Sidebar

Add your component to the sidebar in config/docs.ts

{
    title: "Example Component",
    href: `/docs/components/example-component`,
    items: [],
    label: "New",
}

4. Create docs

Create an MDX file for documenting your component in content/docs/components/example-component.mdx

---
title: Example Component
date: 2024-06-01
description: Example component for Magic UI
author: magicui
published: true
---

<ComponentPreview name="example-component-demo" />

## Installation

<Tabs defaultValue="cli">

<TabsList>
  <TabsTrigger value="cli">CLI</TabsTrigger>
  <TabsTrigger value="manual">Manual</TabsTrigger>
</TabsList>
<TabsContent value="cli">

```bash
npx magicui-cli add example-component
```

</TabsContent>

<TabsContent value="manual">

<Steps>

<Step>Copy and paste the following code into your project.</Step>

<ComponentSource name="example-component" />

<Step>Update the import paths to match your project setup.</Step>

</Steps>

</TabsContent>

</Tabs>

<ComponentSource name="example-component" />

## Props

| Prop  | Type   | Description                | Default |
| ----- | ------ | -------------------------- | ------- |
| color | String | The color of the component | "blue"  |

5. Update Registry

Export your component and example in the registry files:

In registry/registry-ui.ts:

export const ui: Registry = [
  // ... existing components ...
  {
    name: "example-component",
    type: "registry:ui",
    files: ["magicui/example-component.tsx"],
    // Add any dependencies or tailwind configurations if needed
  },
];

In registry/registry-examples.ts:

export const examples: Registry = [
  // ... existing examples ...
  {
    name: "example-component-demo",
    type: "registry:example",
    registryDependencies: ["example-component"],
    files: ["example/example-component-demo.tsx"],
  },
];

Make sure to add any necessary dependencies, tailwind configurations, or other properties as needed for your specific component.

Adding to the showcase

1. Create your showcase as a MDX file

Create your showcase in content/showcase/website-name.mdx

---
title: website-name.com
description: Website description
image: /showcase/website-name.png
href: https://website-name.com
featured: true
affiliation: YC S25, raised $10M
---

2. Create an image

Upload an image of your site to public/showcase/website-name.png

How to use CLI

1. Run CLI script from project root folder

pnpm run install:cli

pnpm run dev:cli

pnpm run build:cli

pnpm run release:cli

The CLI in development uses index.json from default 3000 port on localhost. Otherwise https://magicui.design

Ask for Help

For any help or questions, please open a new GitHub issue.