Requisitos
Antes de começar, certifique-se de ter:
React 16.8+
Hooks são necessários para o SDK funcionar
Node.js 14+
Para gerenciamento de pacotes
Instalar o Pacote
Escolha seu gerenciador de pacotes preferido:
npm install @testlyjs/react
Configurar o Provider
O TestlyProvider deve envolver toda a sua aplicação.
Ele gerencia o estado dos experimentos e se comunica com a API do Testly.
React (Vite/CRA)
Next.js App Router
Next.js Pages Router
Remix
import { TestlyProvider } from '@testlyjs/react';
function App() {
return (
<TestlyProvider apiKey={import.meta.env.VITE_TESTLY_API_KEY}>
{/* Sua aplicação */}
</TestlyProvider>
);
}
export default App;
Criar arquivo .env:VITE_TESTLY_API_KEY=sua_api_key_aqui
import { TestlyProvider } from '@testlyjs/react';
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html lang="pt-BR">
<body>
<TestlyProvider apiKey={process.env.NEXT_PUBLIC_TESTLY_API_KEY}>
{children}
</TestlyProvider>
</body>
</html>
);
}
Criar arquivo .env.local:NEXT_PUBLIC_TESTLY_API_KEY=sua_api_key_aqui
import type { AppProps } from 'next/app';
import { TestlyProvider } from '@testlyjs/react';
export default function App({ Component, pageProps }: AppProps) {
return (
<TestlyProvider apiKey={process.env.NEXT_PUBLIC_TESTLY_API_KEY}>
<Component {...pageProps} />
</TestlyProvider>
);
}
Criar arquivo .env.local:NEXT_PUBLIC_TESTLY_API_KEY=sua_api_key_aqui
import { TestlyProvider } from '@testlyjs/react';
export default function App() {
return (
<html lang="pt-BR">
<head>
<Meta />
<Links />
</head>
<body>
<TestlyProvider apiKey={process.env.TESTLY_API_KEY}>
<Outlet />
</TestlyProvider>
<ScrollRestoration />
<Scripts />
</body>
</html>
);
}
Criar arquivo .env:TESTLY_API_KEY=sua_api_key_aqui
ImportanteSempre use variáveis de ambiente para armazenar sua API Key. Nunca faça commit dela no código!
Configuração do Provider
O TestlyProvider aceita as seguintes props:
| Prop | Tipo | Obrigatório | Descrição |
|---|
apiKey | string | ✅ Sim | Sua chave de API do Testly |
config | object | ❌ Não | Opções de configuração |
Opções de Configuração
<TestlyProvider
apiKey="YOUR_API_KEY"
config={{
debug: boolean, // Ativa logs detalhados (padrão: false)
dedupConversions: boolean, // Previne conversões duplicadas (padrão: true)
baseUrl: string, // URL customizada da API (opcional)
}}
>
<TestlyProvider
apiKey={process.env.NEXT_PUBLIC_TESTLY_API_KEY}
config={{
debug: process.env.NODE_ENV === 'development',
dedupConversions: true
}}
>
<App />
</TestlyProvider>
RecomendadoAtive debug: true em desenvolvimento para facilitar troubleshooting!
Verificar a Instalação
Para garantir que tudo está funcionando, crie um componente de teste:
components/TestInstallation.tsx
'use client'; // Se estiver usando Next.js App Router
import { useExperiment } from '@testly/react';
export function TestInstallation() {
const { variant, loading, error } = useExperiment('test-installation');
if (loading) return <div>Carregando...</div>;
if (error) return <div>Erro: {error.message}</div>;
return (
<div>
<p>✅ Testly instalado com sucesso!</p>
<p>Variante: {variant}</p>
</div>
);
}
Você verá um erro porque o experimento test-installation ainda não existe. Isso é esperado! Vá para o dashboard e crie seu primeiro experimento.
Configurar .gitignore
Adicione suas variáveis de ambiente ao .gitignore:
# Variáveis de ambiente
.env
.env.local
.env*.local
# Logs
npm-debug.log*
yarn-debug.log*
yarn-error.log*
TypeScript
O Testly SDK já vem com tipos TypeScript incluídos. Nenhuma configuração adicional é necessária!
import { TestlyProvider, useExperiment, useConversion } from '@testly/react';
// Todos os tipos estão disponíveis automaticamente
const { variant, loading, error, convert } = useExperiment('my-experiment');
interface ExperimentVariants {
'my-experiment': 'control' | 'variant-b' | 'variant-c';
}
const { variant } = useExperiment<ExperimentVariants['my-experiment']>('my-experiment');
// variant agora tem autocomplete com os valores possíveis
Próximos Passos
Criar primeiro experimento
No dashboard, crie um experimento de teste com 2 variantes
Implementar useExperiment
Troubleshooting
Erro: 'Cannot find module @testly/react'
Solução: Certifique-se de que instalou o pacote:npm install @testly/react
Erro: 'apiKey is required'
Solução: Verifique se sua variável de ambiente está configurada:
- Crie o arquivo
.env ou .env.local
- Adicione:
NEXT_PUBLIC_TESTLY_API_KEY=sua_chave
- Reinicie o servidor de desenvolvimento
Next.js: Variáveis devem começar com NEXT_PUBLIC_ Vite: Variáveis devem começar com VITE_ Variável de ambiente retorna undefined
Checklist:
- ✅ Arquivo
.env está na raiz do projeto?
- ✅ Variável começa com o prefixo correto? (
NEXT_PUBLIC_ ou VITE_)
- ✅ Reiniciou o servidor após criar o arquivo?
- ✅ Não tem espaços ao redor do
=?
# ✅ Correto
NEXT_PUBLIC_TESTLY_API_KEY=abc123
# ❌ Errado (tem espaços)
NEXT_PUBLIC_TESTLY_API_KEY = abc123
Next.js: 'Hooks can only be called inside the body of a function component'
Solução: Se estiver usando Next.js App Router, adicione 'use client' no topo do arquivo:'use client';
import { useExperiment } from '@testly/react';
export function MyComponent() {
// ...
}
TypeScript: Tipos não são reconhecidos
Solução: Verifique seu tsconfig.json:{
"compilerOptions": {
"moduleResolution": "node",
"esModuleInterop": true,
"skipLibCheck": true
}
}
rm -rf node_modules package-lock.json
npm install
Suporte
Precisa de ajuda com a instalação?
