> ## Documentation Index
> Fetch the complete documentation index at: https://docs.testly.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Instalação
> Como instalar e configurar o Testly React SDK no seu projeto
## Requisitos
Antes de começar, certifique-se de ter:
Hooks são necessários para o SDK funcionar
Para gerenciamento de pacotes
[Crie uma conta grátis](https://app.testly.com.br/)
Encontrada em [configurações](https://app.testly.com.br/settings)
***
## Instalar o Pacote
Escolha seu gerenciador de pacotes preferido:
```bash theme={null}
npm install @testlyjs/react
```
```bash theme={null}
yarn add @testlyjs/react
```
```bash theme={null}
pnpm add @testlyjs/react
```
```bash theme={null}
bun add @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.
```tsx src/App.tsx theme={null}
import { TestlyProvider } from '@testlyjs/react';
function App() {
return (
{/* Sua aplicação */}
);
}
export default App;
```
**`Criar arquivo .env:`**
```bash .env theme={null}
VITE_TESTLY_API_KEY=sua_api_key_aqui
```
```tsx app/layout.tsx theme={null}
import { TestlyProvider } from '@testlyjs/react';
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
{children}
);
}
```
**`Criar arquivo .env.local:`**
```bash .env.local theme={null}
NEXT_PUBLIC_TESTLY_API_KEY=sua_api_key_aqui
```
```tsx pages/_app.tsx theme={null}
import type { AppProps } from 'next/app';
import { TestlyProvider } from '@testlyjs/react';
export default function App({ Component, pageProps }: AppProps) {
return (
);
}
```
**`Criar arquivo .env.local:`**
```bash .env.local theme={null}
NEXT_PUBLIC_TESTLY_API_KEY=sua_api_key_aqui
```
```tsx app/root.tsx theme={null}
import { TestlyProvider } from '@testlyjs/react';
export default function App() {
return (
);
}
```
**`Criar arquivo .env:`**
```bash .env theme={null}
TESTLY_API_KEY=sua_api_key_aqui
```
**Importante**
Sempre 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
```tsx theme={null}
void, // Callback de observabilidade (opcional)
}}
>
```
### Exemplo com Debug
```tsx theme={null}
```
**Recomendado**
Ative `debug: true` em desenvolvimento para facilitar troubleshooting!
***
## Verificar a Instalação
Para garantir que tudo está funcionando, crie um componente de teste:
```tsx components/TestInstallation.tsx theme={null}
'use client'; // Se estiver usando Next.js App Router
import { useExperiment } from '@testlyjs/react';
export function TestInstallation() {
const { variant, loading, error } = useExperiment('test-installation');
if (loading) return
Carregando...
;
if (error) return
Erro: {error.message}
;
return (
✅ Testly instalado com sucesso!
Variante: {variant}
);
}
```
Você verá um erro porque o experimento `test-installation` ainda não existe. Isso é esperado! Vá para o [dashboard](https://app.testly.com.br) e crie seu primeiro experimento.
***
## Configurar .gitignore
Adicione suas variáveis de ambiente ao `.gitignore`:
```bash .gitignore theme={null}
# 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!
```tsx theme={null}
import { TestlyProvider, useExperiment } from '@testlyjs/react';
// Todos os tipos estão disponíveis automaticamente
const { variant, loading, error, convert } = useExperiment('my-experiment');
```
Se você quiser tipos personalizados:
```tsx theme={null}
interface ExperimentVariants {
'my-experiment': 'control' | 'variant-b' | 'variant-c';
}
const { variant } = useExperiment('my-experiment');
// variant agora tem autocomplete com os valores possíveis
```
***
## Próximos Passos
Acesse o [dashboard](https://app.testly.com.br) e copie sua API Key
No dashboard, crie um experimento de teste com 2 variantes
Siga o guia [useExperiment](/sdk/use-experiment) para usar o hook
Use `convert('evento')` do próprio `useExperiment` — veja [useExperiment](/sdk/use-experiment)
***
## Troubleshooting
**Solução**: Certifique-se de que instalou o pacote:
```bash theme={null}
npm install @testlyjs/react
```
E que reiniciou o servidor de desenvolvimento após a instalação.
**Solução**: Verifique se sua variável de ambiente está configurada:
1. Crie o arquivo `.env` ou `.env.local`
2. Adicione: `NEXT_PUBLIC_TESTLY_API_KEY=sua_chave`
3. Reinicie o servidor de desenvolvimento
**Next.js**: Variáveis devem começar com `NEXT_PUBLIC_` **Vite**: Variáveis devem começar com `VITE_`
**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 `=`?
```bash theme={null}
# ✅ Correto
NEXT_PUBLIC_TESTLY_API_KEY=abc123
# ❌ Errado (tem espaços)
NEXT_PUBLIC_TESTLY_API_KEY = abc123
```
**Solução**: Se estiver usando Next.js App Router, adicione `'use client'` no topo do arquivo:
```tsx theme={null}
'use client';
import { useExperiment } from '@testlyjs/react';
export function MyComponent() {
// ...
}
```
Componentes que usam hooks React precisam ser Client Components.
**Solução**: Verifique seu `tsconfig.json`:
```json tsconfig.json theme={null}
{
"compilerOptions": {
"moduleResolution": "node",
"esModuleInterop": true,
"skipLibCheck": true
}
}
```
Se o problema persistir, tente:
```bash theme={null}
rm -rf node_modules package-lock.json
npm install
```
***
## Suporte
Precisa de ajuda com a instalação?
[suporte@testly.com.br](mailto:suporte@testly.com.br)
Guia rápido de 5 minutos