> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# Ambiente e configuração

Um único schema validado para todo o workspace.

## Faça uma alteração na configuração e verifique

Comece com um aplicativo Web em execução. No editor abra apps/web/.env.local; se não existir, copie .env.example para lá usando o tutorial da Web. Para uma primeira verificação inofensiva, encontre EMAIL_PROVIDER=local e deixe-o local. Essa configuração envia o e-mail do produto para a visualização local em vez de para uma caixa de entrada real. Não cole linhas KEY=value no terminal.

Para cada serviço habilitado, siga o guia de configuração do provedor, substitua apenas os valores nomeados, salve o arquivo, pare o servidor Web com Ctrl + C e reinicie com o comando abaixo. Se a validação nomear uma chave ausente, reabra esse arquivo e compare essa chave com o guia do provedor. Mantenha root .env sincronizado apenas para valores usados ​​por migrações de banco de dados; copiá-lo sozinho não configura Next.js.

[Procure uma chave de configuração](https://supastack.dev/pt/docs/web/project-structure.md)

[Aprenda como executar um comando e editar um arquivo](https://supastack.dev/pt/docs/web/terminal-basics.md)

```
corepack pnpm --filter @supastack/web dev
```


## Começa pelo exemplo de ambiente

O .env.example raiz é o inventário de configuração. A validação partilhada vive em packages/config. Reveja em conjunto o ambiente de aplicação escolhido e os modos de fornecedor; uma interface local não é uma estratégia de credenciais de produção.

O modo de referência sem credenciais exige uma configuração de aplicação local/test e fornecedores fake/locais. Escolher um fornecedor de produção muda os requisitos do runtime.


## Mantém os segredos atrás da API

Segredos de auth, credenciais de base, chaves de fornecedor, segredos Stripe e credenciais Trigger são só de servidor. Nunca lhes dês prefixo NEXT_PUBLIC_ ou EXPO_PUBLIC_. Não os mostres durante a instalação nem os incluas em respostas de erro.

O browser recebe configuração pública e aliases de modelo permitidos. Propriedade de workspace, decisões de permissão, orçamentos e escolha de fornecedor ficam aplicados no servidor.


## Verifica uma alteração antes de a usar

Valida a configuração através do pacote config existente e corre os testes deterministas relevantes. Usa o caminho de smoke de fornecedor opt-in separado quando estiveres pronto para verificar integrações reais.

```
corepack pnpm test
corepack pnpm check
corepack pnpm build
```


## Instalação e configuração

O packages/config é o único sítio que faz parse de process.env: um schema zod produz um ServerConfig e um PublicConfig tipados, e a seleção de provider expressa-se como kinds — providers.ai, providers.billing, providers.email, providers.jobs, providers.storage resolvem-se cada um num adaptador nomeado mais os seus campos obrigatórios.

Ativar um provider torna as suas credenciais obrigatórias: ativar um sign-in social, o kind de storage s3 ou o kind de email resend falha o arranque nomeando a variável em falta, em vez de uma surpresa de runtime mais tarde.

```
STORAGE_PROVIDER=s3
STORAGE_BUCKET=kit
STORAGE_ENDPOINT=https://s3.example
STORAGE_PUBLIC_BASE_URL=https://cdn.example
# → config rejects the env if a required field is missing
```


## Fluxo de implementação

Lê a config através de parseServerConfig na fronteira do servidor e passa o valor tipado para dentro — não toques em process.env dentro do código de funcionalidades. A config pública é um objeto separado, deliberadamente pequeno, seguro de serializar para o cliente.

O env específico do produto pertence ao schema próprio do produto consumidor. Resiste a fazer crescer o schema do kit para as necessidades de um único produto.


## Verificação e resolução de problemas

Executa os testes do package config depois de alterar o schema, e verifica que uma variável obrigatória em falta se nomeia a si própria no erro. Um env que faz parse localmente mas não em produção normalmente significa um campo obrigatório não documentado.


## Seguinte

[Módulo i18n](https://supastack.dev/pt/docs/modules/i18n.md)