@tapcart/app-studio-components/README.md

A library for accessing global components across different environments with a consistent API

# @tapcart/app-studio-components

A shared library for accessing global components across different environments with a consistent API.

[![npm version](https://img.shields.io/npm/v/@tapcart/app-studio-components.svg)](https://www.npmjs.com/package/@tapcart/app-studio-components)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

## Installation

```bash
npm install @tapcart/app-studio-components
# or
yarn add @tapcart/app-studio-components
```

## Usage

This package provides a consistent way to access global components across different environments (CLI, Dashboard, Next.js app).

### Basic Usage

```jsx
import { useComponents } from '@tapcart/app-studio-components';

function MyBlock() {
  // Get all available components
  const components = useComponents();
  
  // Get a specific component
  const ProductCard = components.ProductCard;
  
  return (
    <div>
      <h2>My Block</h2>
      {ProductCard && <ProductCard product={someProduct} />}
    </div>
  );
}
```

### Setting Up the Provider

Each environment needs to set up a `ComponentProvider` with the appropriate component source:

```jsx
import { ComponentProvider } from '@tapcart/app-studio-components';

// Load components from your source (filesystem, API, etc.)
const componentSource = {
  ProductCard: ProductCardComponent,
  Button: ButtonComponent,
  // ...other components
};

function App() {
  return (
    <ComponentProvider componentSource={componentSource}>
      <YourApp />
    </ComponentProvider>
  );
}
```

## Environment-Specific Implementations

### CLI

In the CLI, components are loaded from the local filesystem:

```jsx
import { ComponentProvider } from '@tapcart/app-studio-components';

// Load components from filesystem
const filesystemComponents = loadComponentsFromFilesystem();

function App() {
  return (
    <ComponentProvider componentSource={filesystemComponents}>
      <Block />
    </ComponentProvider>
  );
}
```

### Dashboard/Next.js

In production environments, components are loaded from the API:

```jsx
import { ComponentProvider } from '@tapcart/app-studio-components';

// Load components from API
const apiComponents = await fetchComponentsFromAPI();

function App() {
  return (
    <ComponentProvider componentSource={apiComponents}>
      <Block />
    </ComponentProvider>
  );
}
```

## Benefits

- **Consistent API**: Use the same code to access components across all environments
- **Environment-Specific Loading**: Each environment can load components differently while maintaining the same interface
- **Simplified Component Usage**: Components are automatically available through the `useComponents` hook
- **Improved Developer Experience**: No need for special flags or configuration

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Additional Benefits

- **Consistent Interface**: The `useComponents` hook behaves identically across all environments
- **Separation of Concerns**: The hook is decoupled from the component source
- **Testability**: Easy to mock components for testing
- **Portability**: Blocks can be moved between environments without changes
- **Maintainability**: Single source of truth for the hook implementation