Desenvolvimento Local

Este guia vai te orientar na configuração do seu ambiente de desenvolvimento local para o SaaS Boilerplate. Ao final deste guia, você terá um ambiente de desenvolvimento totalmente funcional pronto para construir sua próxima aplicação SaaS.

Pré-requisitos

Antes de começar, certifique-se de ter o seguinte instalado em sua máquina:

• Node.js 18+: O SaaS Boilerplate requer Node.js versão 18 ou superior. Baixar Node.js
• Bun ou pnpm: Recomendamos usar o Bun para instalação de pacotes mais rápida e melhor desempenho. Instalar Bun
• Docker: Usado para executar serviços de desenvolvimento local como PostgreSQL. Instalar Docker
• Git: Para controle de versão. Instalar Git

Opções de Instalação

Você tem duas opções para configurar o SaaS Boilerplate:

Opção 1: Usando a CLI (Recomendado)

A maneira mais fácil de começar é usando nossa CLI, que vai te guiar pelo processo de configuração:

npx saas-boilerplate create meu-app-saas

Substitua meu-app-saas pelo nome do seu projeto. A CLI vai:

1. Criar um novo diretório com o nome do seu projeto
2. Configurar o boilerplate com todas as dependências
3. Configurar variáveis de ambiente iniciais
4. Guiar você pelos passos restantes da configuração

Simplesmente siga os prompts da CLI para completar a instalação.

Opção 2: Clonando o Repositório

Alternativamente, você pode clonar o repositório diretamente:

git clone https://github.com/felipebarcelospro/saas-boilerplate
cd saas-boilerplate

Configurando Seu Ambiente de Desenvolvimento

Depois de instalar o SaaS Boilerplate usando qualquer um dos métodos acima, siga estes passos para configurar seu ambiente de desenvolvimento:

Passo 1: Instalar Dependências

Se você usou o método CLI, as dependências já estão instaladas. Se você clonou o repositório, instale as dependências usando Bun:

bun install

Alternativamente, se você preferir usar pnpm:

pnpm install

Passo 2: Configurar Variáveis de Ambiente

Se você usou o método CLI, as variáveis de ambiente básicas já estão configuradas. Caso contrário, copie o arquivo de exemplo de variáveis de ambiente:

cp .env.example .env

Abra o arquivo .env em seu editor de código favorito e atualize as variáveis conforme necessário. Para mais detalhes, consulte o guia de Variáveis de Ambiente.

Passo 3: Iniciar o Banco de Dados de Desenvolvimento

O SaaS Boilerplate usa Docker para executar um banco de dados PostgreSQL localmente. Inicie o banco de dados com:

bun docker:up

Este comando iniciará uma instância PostgreSQL com a configuração especificada no seu arquivo .env.

Passo 4: Executar Migrações do Banco de Dados

Em seguida, aplique as migrações do banco de dados para configurar o esquema do seu banco de dados:

bun db:migrate:dev

Este comando usa o Prisma para aplicar todas as migrações necessárias ao seu banco de dados de desenvolvimento.

Passo 5: Iniciar o Servidor de Desenvolvimento

Agora você está pronto para iniciar o servidor de desenvolvimento:

bun dev

Sua aplicação SaaS Boilerplate agora deve estar rodando em https://localhost:3000.

Trabalhando com o Banco de Dados

Explorando Seu Banco de Dados com Prisma Studio

O Prisma Studio fornece uma interface visual para visualizar e editar os dados em seu banco de dados. Para abrir o Prisma Studio:

bun db:studio

Isso iniciará o Prisma Studio em seu navegador, normalmente em http://localhost:5555.

Criando Novas Migrações

Quando você faz alterações no seu esquema Prisma (prisma/schema.prisma), você precisará criar e aplicar novas migrações:

bun db:migrate:dev --name descreva_suas_alteracoes

Substitua descreva_suas_alteracoes por uma breve descrição das alterações de esquema que você fez.

Trabalhando com Recursos

Gerando Novos Recursos

O SaaS Boilerplate usa Igniter.js para desenvolvimento de API com segurança de tipos. Para criar um novo recurso:

1. Primeiro, defina o esquema do seu recurso em prisma/schema.prisma
2. Execute as migrações para atualizar seu banco de dados:
   bun db:migrate:dev --name adicionar_seu_recurso
   

3. Gere o recurso usando a CLI do Igniter.js:
   bun igniter generate feature
   

4. Selecione seu recurso nas opções disponíveis

Isso gerará todos os arquivos necessários para seu recurso, incluindo:

• Tipos e interfaces
• Controladores com autenticação adequada
• Procedimentos com lógica de negócios
• Rotas de API com multilocação baseada em organização

Entendendo a Estrutura do Recurso

Cada recurso segue uma estrutura consistente:

src/features/seu-recurso/
├── controllers/         # Endpoints de API e manipulação de requisições
├── procedures/          # Lógica de negócios e operações de banco de dados
├── presentation/        # Componentes de UI
│   ├── components/      # Componentes React
│   └── hooks/           # Hooks React personalizados
├── seu-recurso.interface.ts  # Interfaces TypeScript
└── seu-recurso.router.ts     # Registro de rotas de API

Trabalhando com Autenticação

O SaaS Boilerplate usa um sistema de autenticação baseado em funções com multilocação baseada em organização. Para acessar a autenticação em seus recursos:

// No seu controlador
const auth = await context.auth.getSession({
  requirements: 'authenticated',
  roles: ['admin', 'owner', 'member']
})

// Acesse a organização atual
const organizationId = auth.organization.id

Configurando Webhooks do Stripe

Para desenvolvimento local com pagamentos do Stripe, você precisará configurar o encaminhamento de webhooks:

1. Instale a CLI do Stripe em https://stripe.com/docs/stripe-cli
2. Execute o seguinte comando para encaminhar webhooks do Stripe para seu servidor local:

bun stripe:webhook

Isso encaminhará eventos de webhook do Stripe para seu servidor de desenvolvimento local em https://localhost:3000/api/billing/webhook.

Melhores Práticas de Desenvolvimento

Estrutura de Código

O SaaS Boilerplate segue uma arquitetura baseada em recursos, com código organizado nos seguintes diretórios:

• src/saas-boilerplate/: Recursos principais do SaaS (autenticação, faturamento, organizações)
• src/app/: Páginas do roteador de aplicativos Next.js organizadas por seção
  • (dashboard)/: Páginas de aplicativo protegidas
  • (site)/: Páginas de marketing públicas
  • (auth)/: Páginas de autenticação
• src/content/: Documentação, posts de blog e outro conteúdo
• src/core/: Componentes principais, provedores e utilitários
• src/features/: Seus recursos específicos de aplicativo

Multilocação Baseada em Organização

Todos os recursos no SaaS Boilerplate seguem uma arquitetura multilocatária baseada em organização:

• Cada entidade está relacionada a uma organização, não a usuários individuais
• Os usuários pertencem a organizações com funções específicas
• As solicitações de API são limitadas à organização atual
• As permissões são aplicadas com base nas funções dos usuários dentro das organizações

TypeScript e Segurança de Tipos

Todo o código no SaaS Boilerplate é escrito em TypeScript com tipagem forte. O Igniter.js fornece segurança de tipos de ponta a ponta, do esquema do banco de dados aos endpoints da API e componentes React.

Testes

O SaaS Boilerplate usa Vitest para testes. Você pode executar testes com:

bun test

Provedores de Banco de Dados para Deploy

Enquanto o SQLite é ótimo para desenvolvimento local, para ambientes de produção recomendamos usar um banco de dados PostgreSQL. Aqui estão algumas opções recomendadas:

NeonDB

NeonDB é um serviço de PostgreSQL serverless com um plano gratuito generoso, ideal para projetos em estágio inicial. Oferece:

• Escalonamento automático
• Armazenamento ilimitado (pague apenas pelo que usar)
• Ramificação de banco de dados para ambientes de teste
• Integração fácil com Prisma

Supabase

Supabase oferece um banco de dados PostgreSQL com recursos adicionais como autenticação e armazenamento. É uma excelente opção se você quiser:

• Interface de administração amigável
• Recursos adicionais além do banco de dados
• Plano gratuito para desenvolvimento

Railway

Railway é uma plataforma de deploy completa que oferece PostgreSQL gerenciado com:

• Configuração simples com um clique
• Escalonamento automático
• Monitoramento integrado
• Backups automáticos

Planetscale

Planetscale é um serviço de banco de dados MySQL compatível com Prisma que oferece:

• Ramificação de banco de dados
• Migrações sem tempo de inatividade
• Escalonamento automático
• Plano gratuito para desenvolvimento

Para configurar seu banco de dados de produção, atualize a variável de ambiente DATABASE_URL com a string de conexão do seu provedor escolhido.

Próximos Passos

Agora que você configurou seu ambiente de desenvolvimento local, você pode querer:

• Aprender sobre Variáveis de Ambiente
• Seguir o guia de Primeiros Passos para criar seu primeiro recurso
• Explorar os Recursos Principais do SaaS Boilerplate