MaquinaWeb UI

A minimal React component library built with TypeScript, formatted with Biome, and powered by Bun.

🚀 Quick Start

Prerequisites

• Bun installed on your system

Installation

# Install dependencies
bun install

🛠️ Development

Run Next.js Dev Server

Preview components in a Next.js environment:

bun dev

Open http://localhost:3000 to see the preview.

Run React Cosmos

Develop components in isolation with React Cosmos. React Cosmos uses Next.js as a renderer, so you need both running:

Terminal 1 - Start Next.js:

bun dev

Terminal 2 - Start Cosmos:

bun cosmos

Open http://localhost:5000 to see the Cosmos UI.

Note: Cosmos connects to Next.js running at http://localhost:3000/cosmos/ to render your fixtures.

Linting & Formatting

# Check for issues
bun lint

# Fix issues automatically
bun lint:fix

# Format code
bun format

🏗️ Building

Build the library for publishing:

bun build

This will:

• Generate ESM bundles in the dist/ directory
• Create TypeScript declaration files (.d.ts)
• Add source maps for debugging

🚀 Deploying to Vercel

You can deploy your Cosmos component documentation to Vercel with automatic configuration.

Quick Start:

1. Push your code to GitHub/GitLab/Bitbucket
2. Connect your repository at vercel.com
3. Click Deploy - it will use the pre-configured vercel.json settings
4. Your Cosmos documentation will be live! 🎉

Configuration is already set up:

• ✅ Build Command: bun run build:vercel
• ✅ Output Directory: cosmos-export
• ✅ Install Command: bun install

📖 For detailed instructions in Portuguese, see DEPLOY_VERCEL.md

Manual Build (optional):

bun run build:vercel

This will build Next.js and export static Cosmos files to cosmos-export/.

📤 Publishing

Este projeto usa semantic-release para automatizar versionamento e publicação.

🤖 Publicação Automática (Recomendado)

O versionamento e publicação são 100% automáticos via GitHub Actions:

1. Configure o NPM_TOKEN no GitHub:

   • Gere um token em npmjs.com → Settings → Access Tokens
   • Adicione como secret NPM_TOKEN no repositório GitHub

2. Configure o package.json (já configurado):

   {
     "name": "maquinaweb-ui",
     "author": "MaquinaWeb",
     "repository": {
       "type": "git",
       "url": "https://github.com/maquinaweb/maquinaweb-ui.git"
     }
   }

3. Faça commits usando Conventional Commits:

   git commit -m "feat: adiciona novo componente"  # → versão minor
   git commit -m "fix: corrige bug no Button"       # → versão patch
   git commit -m "feat!: breaking change"           # → versão major

4. Push para main:

   git push origin main

O GitHub Actions automaticamente vai:

• ✅ Executar testes e build
• ✅ Determinar a nova versão
• ✅ Gerar/atualizar CHANGELOG.md
• ✅ Criar release no GitHub
• ✅ Publicar no npm

📖 Para mais detalhes, veja SEMANTIC_RELEASE.md

🔧 Publicação Manual (Opcional)

Se preferir publicar manualmente:

# Login no npm
npm login

# Execute o semantic-release localmente
bunx semantic-release

🎯 Client vs Server Components

Esta biblioteca suporta tanto Client Components quanto Server Components do Next.js.

Client Components (Atual)

Componentes atuais usam 'use client' porque precisam de:

• ✅ React hooks (useState, useEffect, etc.)
• ✅ Event handlers (onClick, onChange, etc.)
• ✅ Animações com Motion
• ✅ Bibliotecas client-only

Estrutura de um Client Component:

// src/components/my-client-component/index.ts
'use client';  // ← Diretiva necessária

export { MyClientComponent } from './my-client-component';

// src/components/my-client-component/my-client-component.tsx
'use client';  // ← Diretiva necessária

import { useState } from 'react';

export const MyClientComponent = () => {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(count + 1)}>{count}</button>;
};

Server Components (Futuro)

Para componentes que não precisam de interatividade:

• ✅ Componentes puramente visuais
• ✅ Layouts e containers estáticos
• ✅ Componentes que apenas exibem dados

Estrutura de um Server Component:

// src/components/my-server-component/index.ts
// SEM 'use client'  ← Pode ser renderizado no servidor

export { MyServerComponent } from './my-server-component';

// src/components/my-server-component/my-server-component.tsx
// SEM 'use client'

export const MyServerComponent = ({ title, children }) => {
  return (
    <div className="card">
      <h3>{title}</h3>
      {children}
    </div>
  );
};

Decisão: Client ou Server?

| Recurso | Client | Server | |---------|--------|--------| | React Hooks (useState, useEffect) | ✅ | ❌ | | Event Handlers (onClick, onChange) | ✅ | ❌ | | Motion/Framer Motion | ✅ | ❌ | | Browser APIs (window, document) | ✅ | ❌ | | Apenas exibição de dados | ✅ | ✅ | | SEO otimizado | ⚠️ | ✅ | | Menor bundle size | ⚠️ | ✅ |

📖 Para mais detalhes, veja ARCHITECTURE.md

📝 Adding New Components.

🤖 Automático - Exports são Gerados Automaticamente!

Ao criar um novo componente, os exports do package.json são atualizados automaticamente no build.

1. Create a new component directory (use kebab-case):

   mkdir -p src/components/your-component

2. Create the component file:

   // src/components/your-component/YourComponent.tsx
   export interface YourComponentProps {
     // Your props
   }
   
   export function YourComponent(props: YourComponentProps) {
     // Your implementation
     return <div>Hello</div>;
   }

3. REQUIRED: Create an index file:

   // src/components/your-component/index.ts
   export { YourComponent } from "./YourComponent";
   export type { YourComponentProps } from "./YourComponent";

4. (Optional) Create Cosmos fixtures:

   // src/components/your-component/YourComponent.fixture.tsx
   import { YourComponent } from "./YourComponent";
   
   export default {
     "Default": <YourComponent />,
     "Variant": <YourComponent variant="custom" />,
   };

5. (Optional) Export from the main entry point:

   // src/index.ts
   export { YourComponent } from "./components/your-component";
   export type { YourComponentProps } from "./components/your-component";

6. Build and it's ready!

   bun run build
   # ✅ Automatically updates package.json exports
   # ✅ Creates maquinaweb-ui/your-component entrypoint

📖 Exports são gerados automaticamente! Veja:

• Apenas exports base são versionados no Git (via git hooks)
• Exports completos são gerados no build local (para testes)
• Exports completos são gerados no publish (via prepublishOnly)

Para mais detalhes: GIT_EXPORTS.md

🔧 Configuration Files

tsup.config.ts

Handles the build process:

• Bundles TypeScript to ESM
• Generates type declarations
• Adds "use client" directive for Next.js compatibility
• Excludes React/React-DOM from bundle

cosmos.config.json

Configures React Cosmos:

• Uses custom renderer URL to connect with Next.js
• Watches src directory for changes
• Static files served from public directory

biome.json

Linting and formatting rules:

• 2-space indentation
• Double quotes
• Semicolons required
• 100 character line width

tsconfig.json

TypeScript configuration:

• ESNext target for modern JavaScript
• Bundler module resolution
• Strict type checking enabled
• Next.js plugin support

📚 Example Component Usage

After installing your published package:

⚠️ Important: Esta biblioteca usa apenas imports individuais

Não existe um export principal. Você deve importar de cada componente específico:

// ✅ Correto - Import individual de cada componente
import { TextField, InputText } from "maquinaweb-ui/text-field";
import { ContainerAnimation } from "maquinaweb-ui/container-animation";
import { SplitTextPoor } from "maquinaweb-ui/split-text-poor";

function App() {
  return (
    <ContainerAnimation>
      <SplitTextPoor>
        <h1>Hello World</h1>
      </SplitTextPoor>
      <TextField name="email" label="Email" />
    </ContainerAnimation>
  );
}

// ❌ Errado - Não há export principal
import { TextField } from "maquinaweb-ui"; // Isso NÃO vai funcionar

🎯 Benefícios dos Imports Individuais

1. Tree-shaking perfeito - Só importa o que você usa
2. Bundle size menor - Cada componente é um bundle separado
3. Auto-imports corretos - IDEs sugerem o import correto automaticamente
4. Tipos otimizados - TypeScript carrega apenas os tipos necessários

📦 Tamanhos dos Bundles

| Componente | Tamanho (gzipped) | |------------|-------------------| | text-field | ~2.85 kB | | container-animation | ~1.54 kB | | split-text-poor | ~0.87 kB |

📖 For detailed usage and bundle size comparison, see ENTRYPOINTS.md

🤝 Contributing

1. Create a new branch for your feature
2. Develop your component with Cosmos fixtures
3. Test in the Next.js preview environment
4. Run linting and formatting
5. Build to ensure no errors
6. Submit a pull request

📄 License

MIT