> ## Documentation Index
> Fetch the complete documentation index at: https://magicpatterns.mintlify.site/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# NPM Package

> Connect your published React component library so the AI uses your real code

<Note>
  [Book a call](https://cal.com/mp-daniel/30min) and our team will help set this
  up. We are working towards making this self-serve!
</Note>

Connecting a published component library brings your existing React components into Magic Patterns. After everything is connected, the AI will:

* Use your actual component code in generated designs
* Respect your component APIs, props, and variants
* Generate code with correct import paths
* Stay consistent with your design system

<Info>
  Everything on this page is guidance, not a checklist. We work with you during
  onboarding and adapt to how your team already ships components. For example,
  we have connected teams using the public NPM registry, private NPM, and GitHub
  Packages (an npm-compatible registry with a read-only token and `.npmrc`
  scoped to your organization). Prefer working from a repository instead? See
  [linking GitHub](/documentation/design-systems/importing/github).
</Info>

## What we need

To import your components, we need two things:

1. **Component code**: either via an NPM package plus access token, or a zip or tar bundle you send manually. This lets us render the components in the Magic Patterns editor and ensures visual parity.
2. **Component documentation**: either via Storybook or a custom MCP. This serves as context for the AI to understand your components and when to use each one.

NPM, GitHub Packages, and other private registries are different ways to host and version the same package artifact; a zip, tar, or `npm pack` tarball you send manually fills the same role.

## Package structure

We recommend keeping Storybook files next to your component sources so documentation stays close to the code and is easier for the AI to relate to usage.

```
my-design-system/
├── package.json
├── src/
│   ├── components/
│   │   ├── Button/
│   │   │   ├── Button.tsx
│   │   │   ├── Button.stories.tsx    # Storybook file
│   │   │   └── index.ts
│   │   ├── Card/
│   │   │   ├── Card.tsx
│   │   │   ├── Card.stories.tsx
│   │   │   └── index.ts
│   │   └── index.ts                  # Re-exports all components
│   └── index.ts                      # Main entry point
└── dist/                             # Compiled output
```

<CardGroup cols={2}>
  <Card title="React Components" icon="react">
    Your code must be written in React.
  </Card>
</CardGroup>

## Ways to share

<Tabs>
  <Tab title="Registry token">
    If your package is on a private registry (NPM, GitHub Packages, or another npm-compatible host), share a read-only access token.

    ```bash theme={null}
    # Generate a read-only token
    npm token create --read-only
    ```

    Share this token securely with your Magic Patterns contact.
  </Tab>

  <Tab title="Manual Bundle">
    You can also send a zip or tar bundle of your component library.

    ```bash theme={null}
    # Create a tarball of your package
    npm pack
    ```

    That produces a `.tgz` file you can send to us directly.
  </Tab>
</Tabs>

## Documentation best practices

Good documentation helps the AI understand not only what your components do, but when to use them.

<Warning>
  Listing props alone is not enough. The AI needs context about when to pick one
  component or variant over another.
</Warning>

### Usage guidance

For each component, cover:

* Purpose: what problem the component solves
* When to use: which scenarios should lead to this component
* When not to use: anti-patterns or wrong fits
* Variants: when each variant is appropriate

```tsx theme={null}
/**
 * Button component for user actions.
 *
 * @usage
 * - Use `primary` variant for the main call-to-action on a page
 * - Use `secondary` variant for less important actions
 * - Use `destructive` variant only for delete/remove actions
 * - Use `ghost` variant for tertiary actions or in toolbars
 *
 * @when-not-to-use
 * - Do not use Button for navigation; use Link instead
 * - Do not use multiple primary buttons in the same section
 */
export const Button = ({ variant, size, children, ...props }) => {
  // ...
}
```

## Working with multiple packages

Many design systems split across packages that depend on each other. Magic Patterns supports that layout.

<CardGroup cols={2}>
  <Card title="Monorepo" icon="folder-tree">
    Multiple packages in one repository (for example Yarn workspaces, Turborepo,
    or Nx)
  </Card>

  <Card title="Multi-Repo" icon="code-branch">
    Separate repositories for packages that depend on each other
  </Card>
</CardGroup>

If packages depend on each other, we account for that when syncing:

```
@mycompany/tokens        # Design tokens (colors, spacing, etc.)
@mycompany/primitives    # Low-level components (Box, Text, etc.)
@mycompany/components    # High-level components (Card, Modal, etc.)
```

The AI can:

* Import from the correct package
* Use shared tokens in a consistent way
* Respect your component layering

For multiple packages, plan to share:

1. Package list: every package that belongs to the design system
2. Dependency graph: how those packages relate
3. Access tokens: credentials for each private package when needed

<Tip>
  In a monorepo, one access token often covers every package in the workspace.
</Tip>

Generated code can then follow your structure:

```tsx theme={null}
import { colors, spacing } from '@mycompany/tokens'
import { Box, Text } from '@mycompany/primitives'
import { Card, Button } from '@mycompany/components'

export const PricingCard = () => {
  return (
    <Card>
      <Box padding={spacing.lg}>
        <Text color={colors.primary}>Premium Plan</Text>
        <Button variant="primary">Get Started</Button>
      </Box>
    </Card>
  )
}
```

## Next steps

<Card title="Schedule a call" icon="envelope" href="https://cal.com/mp-daniel/30min">
  Book time to plan connecting your real component library with your team.
</Card>