Setup & Instalação

Instalando os packages

Há três formas de instalar os packages do monorepo. Escolha a que se encaixa melhor no seu contexto.

Via GitHub (recomendado)
Via path local
Via npm (futuro)

A forma mais simples enquanto os packages não são publicados no npm. Instala diretamente de um commit, branch ou tag do GitHub.

# Instalar pelo branch main
npm install "https://github.com/Easy-Goal/easygoal-ui#main"

# Instalar uma versão específica (tag)
npm install github:easygoal/easygoal-ui#v0.1.0

O npm resolve o package usando o package.json na raiz. Para instalar um sub-package específico do monorepo, aponte para o diretório correto via package.json#exports ou use um path local.

Para instalar os packages via GitHub, adicione ao package.json do seu projeto:

{
  "dependencies": {
    "@easygoal/packages": "github:Easy-Goal/easygoal-monorepo"
  }
}

Em seguida rode npm install ou pnpm install.

Ideal durante desenvolvimento quando você tem o monorepo clonado localmente.

# Clonar o monorepo
git clone https://github.com/Easy-Goal/easygoal-monorepo.git ~/projects/easy/easygoal-monorepo

# No projeto onde vai usar
cd ~/projects/easy/app-front

# Instalar os packages pelo path relativo
npm install ../easygoal-monorepo/packages/ui
npm install ../easygoal-monorepo/packages/auth

Com pnpm, use o protocolo workspace: se você trabalhar com os projetos dentro do mesmo workspace, ou link: para paths locais fora do workspace:

pnpm add link:../easygoal-monorepo/packages/ui
pnpm add link:../easygoal-monorepo/packages/auth

Rode o build do package em modo watch em um terminal separado:

cd ~/projects/easy/easygoal-monorepo
pnpm build:ui   # ou pnpm build:auth
# modo watch:
pnpm --filter @easygoal/ui run dev

Quando os packages forem publicados no npm (ou no GitHub Packages):

# npm público
npm install @easygoal/ui @easygoal/auth

# GitHub Packages (registry privado)
npm install @easygoal/ui @easygoal/auth \
  --registry https://npm.pkg.github.com

Para GitHub Packages, adicione um .npmrc na raiz do projeto:

# .npmrc
@easygoal:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NPM_TOKEN}

E defina NPM_TOKEN com um Personal Access Token (PAT) do GitHub com permissão read:packages.

Usando @easygoal/ui

import { Logo, colors } from "@easygoal/packages/ui";

// Logo no tema escuro (texto branco, ícone laranja)
<Logo variant="dark" width={133} />

// Logo no tema claro (texto escuro, ícone laranja)
<Logo variant="light" width={100} />

// Tokens de cor
const bg = colors.background;   // "#0F1729"
const accent = colors.primary;  // "#F97316"

Importando apenas os tokens (sem carregar o componente React):

import { colors, cssVars } from "@easygoal/packages/ui/tokens";

Usando @easygoal/auth

O @easygoal/auth é específico para projetos Next.js + Supabase que integram com o SSO Easy Goal.

1. EgSessionProvider (layout raiz)

// app/layout.tsx
import { EgSessionProvider } from "@easygoal/packages/auth";
import { createClient } from "@/utils/supabase/client";

export default function RootLayout({ children }) {
  return (
    <EgSessionProvider
      config={{
        loginUrl: process.env.NEXT_PUBLIC_SSO_URL!,
        appUrl: process.env.NEXT_PUBLIC_APP_URL!,
      }}
      supabaseClient={createClient()}
    >
      {children}
    </EgSessionProvider>
  );
}

2. Callback route

// app/auth/callback/route.ts
import { createCallbackRoute } from "@easygoal/packages/auth";

export const GET = createCallbackRoute({
  supabaseUrl: process.env.NEXT_PUBLIC_SUPABASE_URL!,
  supabaseAnonKey: process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
  ssoUrl: process.env.NEXT_PUBLIC_SSO_URL,
  appUrl: process.env.NEXT_PUBLIC_APP_URL,
});

3. Middleware

// middleware.ts
import { updateSession, defaultMatcherConfig } from "@easygoal/packages/auth";
import type { NextRequest } from "next/server";

export async function middleware(request: NextRequest) {
  return updateSession(request, {
    supabaseUrl: process.env.NEXT_PUBLIC_SUPABASE_URL!,
    supabaseAnonKey: process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
  });
}

export const config = defaultMatcherConfig;

4. Hook de sessão

"use client";
import { useAuthSession } from "@easygoal/packages/auth";

export function Header() {
  const { session, signOut, isReady } = useAuthSession();

  if (!isReady) return null;

  return (
    <header>
      <span>{session?.user.email}</span>
      <button onClick={signOut}>Sair</button>
    </header>
  );
}

Rodando o monorepo localmente

# Pré-requisito: pnpm
npm install -g pnpm

# Clonar
git clone https://github.com/Easy-Goal/easygoal-monorepo.git
cd easygoal-monorepo

# Instalar dependências de todos os packages
pnpm install

# Build de tudo
pnpm build

# Build individual
pnpm build:ui
pnpm build:auth

# Watch mode (desenvolvimento)
pnpm --filter @easygoal/ui run dev
pnpm --filter @easygoal/auth run dev

Integração de Webhooks

Para aceitar webhooks em múltiplas linguagens, o SSO expõe POST /api/webhook/payment e valida a assinatura HMAC SHA256:

Node.js
Python
Go

import { createHmac, timingSafeEqual } from 'crypto';

function verifyWebhook(rawBody: string, signature: string, secret: string): boolean {
  const expected = createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  const sigBuf = Buffer.from(signature, 'hex');
  const expBuf = Buffer.from(expected, 'hex');

  return sigBuf.length === expBuf.length && timingSafeEqual(sigBuf, expBuf);
}

import hmac, hashlib

def verify_webhook(raw_body: str, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), raw_body.encode(), hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

import ("crypto/hmac"; "crypto/sha256"; "encoding/hex")

func verifyWebhook(rawBody, signature, secret string) bool {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(rawBody))
    expected := hex.EncodeToString(mac.Sum(nil))
    return hmac.Equal([]byte(signature), []byte(expected))
}

Visão Geral

Monorepo

Setup & Instalação

Instalando os packages

Usando @easygoal/ui

Usando @easygoal/auth

1. EgSessionProvider (layout raiz)

2. Callback route

3. Middleware

4. Hook de sessão

Rodando o monorepo localmente

Integração de Webhooks

​Instalando os packages

​Usando @easygoal/ui

​Usando @easygoal/auth

​1. EgSessionProvider (layout raiz)

​2. Callback route

​3. Middleware

​4. Hook de sessão

​Rodando o monorepo localmente

​Integração de Webhooks

Instalando os packages

Usando @easygoal/ui

Usando @easygoal/auth

1. EgSessionProvider (layout raiz)

2. Callback route

3. Middleware

4. Hook de sessão

Rodando o monorepo localmente

Integração de Webhooks