Instalação

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

Conta Testly

Crie uma conta grátis

API Key

Encontrada em configurações

Instalar o Pacote

Escolha seu gerenciador de pacotes preferido:

npm
yarn
pnpm
bun

npm install @testlyjs/react

yarn add @testlyjs/react

pnpm add @testlyjs/react

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.

React (Vite/CRA)
Next.js App Router
Next.js Pages Router
Remix

src/App.tsx

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:

.env

VITE_TESTLY_API_KEY=sua_api_key_aqui

app/layout.tsx

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:

.env.local

NEXT_PUBLIC_TESTLY_API_KEY=sua_api_key_aqui

pages/_app.tsx

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:

.env.local

NEXT_PUBLIC_TESTLY_API_KEY=sua_api_key_aqui

app/root.tsx

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:

.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)
    autoTrackImpressions: boolean,   // Rastreia impressões automaticamente (padrão: true)
    supabaseUrl: string,             // URL Supabase customizada (opcional)
    onLog: (log) => void,            // Callback de observabilidade (opcional)
  }}
>

Exemplo com Debug

<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 '@testlyjs/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:

.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 } from '@testlyjs/react';

// Todos os tipos estão disponíveis automaticamente
const { variant, loading, error, convert } = useExperiment('my-experiment');

Se você quiser tipos personalizados:

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

Obter API Key

Acesse o dashboard e copie sua API Key

Criar primeiro experimento

No dashboard, crie um experimento de teste com 2 variantes

Implementar useExperiment

Siga o guia useExperiment para usar o hook

Rastrear conversões

Use convert('evento') do próprio useExperiment — veja useExperiment

Troubleshooting

Erro: 'Cannot find module @testlyjs/react'

Solução: Certifique-se de que instalou o pacote:

npm install @testlyjs/react

E que reiniciou o servidor de desenvolvimento após a instalação.

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 '@testlyjs/react';

export function MyComponent() {
  // ...
}

Componentes que usam hooks React precisam ser Client Components.

TypeScript: Tipos não são reconhecidos

Solução: Verifique seu tsconfig.json:

tsconfig.json

{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

Se o problema persistir, tente:

rm -rf node_modules package-lock.json
npm install

Suporte

Precisa de ajuda com a instalação?

Email

suporte@testly.com.br

Documentação

Guia rápido de 5 minutos

Primeiros Passos

SDK

Guias

Requisitos

React 16.8+

Node.js 14+

Conta Testly

API Key

Instalar o Pacote

Configurar o Provider

Configuração do Provider

Opções de Configuração

Exemplo com Debug

Verificar a Instalação

Configurar .gitignore

TypeScript

Próximos Passos

Troubleshooting

Suporte

Email

Documentação

​Requisitos

React 16.8+

Node.js 14+

Conta Testly

API Key

​Instalar o Pacote

​Configurar o Provider

​Configuração do Provider

​Opções de Configuração

​Exemplo com Debug

​Verificar a Instalação

​Configurar .gitignore

​TypeScript

​Próximos Passos

​Troubleshooting

​Suporte

Email

Documentação

Requisitos

Instalar o Pacote

Configurar o Provider

Configuração do Provider

Opções de Configuração

Exemplo com Debug

Verificar a Instalação

Configurar .gitignore

TypeScript

Próximos Passos

Troubleshooting

Suporte