RNTemplate — Template Expo + React Native

Um template mínimo para iniciar apps Expo + React Native com convenções já preparadas:

• TypeScript configurado (via tsconfig.json)
• Navegação (React Navigation) com Stack + Bottom Tabs
• Estrutura de pastas (páginas, features, estilos, routes, store)
• ESLint + Prettier configurados (Husky + lint-staged incluídos para pre-commit)

Este README explica como usar e personalizar o template rapidamente.

Sumário

• Quickstart
• Scripts úteis
• Lint / Prettier / Husky
• Estrutura do projeto e como adicionar páginas/rotas
• Store / API (RTK Query)
• Tipos TypeScript e módulos sem tipos
• Troubleshooting comuns
• Próximos passos e personalizações sugeridas
• Publicação no npm (via GitHub Actions)

Quickstart

1. Instale dependências

npm install --legacy-peer-deps

Se você usa yarn ou pnpm adapte o comando conforme a sua preferência.

2. Instale os hooks do Husky (preparar git hooks)

npm run prepare
# ou (manual)
npx husky install

3. Rodar o projeto (Expo)

npm run start
# abrir no iOS / Android / Web
npm run ios
npm run android
npm run web

4. Validar TypeScript e formatar código

# checar tipos (sem emitir build)
npx tsc --noEmit

# formatar código (Prettier)
npm run format

Scripts importantes (package.json)

• npm run start — inicia o Metro/Expo
• npm run ios / npm run android / npm run web — abre para a plataforma correspondente
• npm run lint — executa ESLint (configável)
• npm run lint:fix — aplica correções automáticas onde possível
• npm run format — executa Prettier
• npm run prepare — instala os hooks do Husky

Lint / Prettier / Husky

O template já contém configuração mínima:

• .eslintrc.js com extends: ['universe/native'] (sua preferência de config)
• eslint.config.cjs neutralizado para evitar conflito com flat config
• .prettierrc e .prettierignore prontos
• husky + lint-staged configurados: pre-commit executa lint-staged

Se quiser executar os checks localmente:

# listar problemas de lint
npm run lint

# tentar corrigir automaticamente
npm run lint:fix

Se os hooks não estiverem ativos (por exemplo, em CI ou após clonar):

npm run prepare

Nota: em ambientes com problemas de peers ou tokens de npm você pode precisar rodar:

npm config delete //registry.npmjs.org/:_authToken
npm login
# depois
npm install --legacy-peer-deps

Estrutura do projeto (visão rápida)

Principais pastas:

• src/pages/ — telas (ex.: Home, Login, etc). O template já tem placeholders.
• src/routes/ — onde o Router/Navigation vive (src/routes/index.tsx já transformado em template)
• src/features/ — features domain-driven (ex.: account, api — RTK Query slices)
• src/store/ — configuração do Redux / store
• src/styles/ — theme, styled.d.ts e tokens
• src/hooks/ — providers / wrappers do app (ThemeProvider, NavigationContainer)
• src/@types/ — declarações de módulos e tipos globais

Como adicionar uma tela simples e conectá-la nas rotas:

1. Criar arquivo src/pages/MinhaPagina/index.tsx com um componente React Native.
2. Importar a tela em src/routes/index.tsx (ou mover o placeholder para o arquivo novo).
3. Adicionar um Tab.Screen ou Stack.Screen conforme desejar.

Exemplo rápido (conceptual):

// src/pages/MinhaPagina/index.tsx
import React from 'react';
import { View, Text } from 'react-native';
export default function MinhaPagina() {
  return (
    <View><Text>Minha página</Text></View>
  );
}

E em src/routes/index.tsx adicione a rota ao Tab.Navigator.

Store e API (RTK Query)

O template inclui um apiSlice pronto para injeção de endpoints e um setupStore em src/store/store.ts.

• src/features/api/apiSlice.ts — base para RTK Query (configure baseUrl e o token se necessário)
• Para criar endpoints de exemplo, veja o src/features/account/exampleSlice.ts já incluído como template CRUD usando apiSlice.injectEndpoints.

Para usar o store em sua aplicação, configure o provider no App.tsx (ou em src/hooks) e passe o store:

import { Provider } from 'react-redux';
import { setupStore } from './src/store/store';
const store = setupStore();

// ... wrap your App with <Provider store={store}> ...

Tipos TypeScript e módulos sem tipos

Alguns pacotes não fornecem typings. Para evitar erros do TypeScript o template inclui src/@types/index.d.ts com declarações genéricas para imagens e alguns pacotes. Recomenda-se instalar tipos oficiais quando existirem:

npm i -D @types/react @types/react-native

Se você adicionar uma dependência que não tem tipos, adicione uma declaração minimal em src/@types/index.d.ts como:

declare module 'nome-do-pacote';

Troubleshooting comum

• Erro ao instalar pacotes: ERESOLVE ou conflito de peer
  • Tente: npm install --legacy-peer-deps
• Erro Access token expired or revoked no npm install
  • Refaça login: npm logout e npm login ou delete o token local:

npm config delete //registry.npmjs.org/:_authToken
npm login

• Erro do TypeScript sobre .tsx / --jsx is not set

  • Solução: tsconfig.json já tem "jsx": "react-jsx" configurado. Se estiver faltando, adicione.

• Regras do ESLint/Flat config conflitando

  • O template inclui .eslintrc.js (legacy) e eslint.config.cjs neutralizado. Se preferir usar a config flat, remova .eslintrc.js e mantenha eslint.config.cjs.

Publicação no npm (via GitHub Actions)

Este template já tem duas opções para publicar no npm a partir do repositório:

1. Publicação por tag (manual)

• Criar uma tag com formato vX.Y.Z e dar push. Exemplo local:

npm run release -- 1.0.2
# isso executa: git tag -a v1.0.2 -m "Release v1.0.2" && git push origin v1.0.2

• O workflow .github/workflows/publish.yml será disparado no push da tag e executará (instalação, lint, tsc, build, publish).

2. Publicação automática com semantic-release (recomendada para releases automáticas)

• Push para a branch main acionará .github/workflows/release.yml que executa semantic-release.
• semantic-release analisa commits (conventional commits) e gera a nova versão, atualiza CHANGELOG.md, faz npm publish e cria uma release no GitHub.

Requisitos / configurações

• Adicione o secret NPM_TOKEN no repositório (Settings → Secrets and variables → Actions)
  • Nome: NPM_TOKEN
  • Valor: token de automação do npm (crie em https://www.npmjs.com/settings/tokens)
• GITHUB_TOKEN é provido automaticamente pelo GitHub Actions; não é necessário configurá-lo manualmente.

Qual usar?

• Se você prefere controlar as versões manualmente (tagging), use a opção (1).
• Se quer CI/CD para releases automáticas com base em commits (convencional), use (2) e siga o padrão conventional commits (feat, fix, perf, chore, etc.).

Próximos passos e personalizações sugeridas

• Defina baseUrl da API em src/features/api/apiSlice.ts e configure as rotas reais.
• Substitua placeholders em src/pages/* por componentes reais e desça a árvore.
• Adicione/atualize tokens e temas em src/styles/theme.ts.
• Ajuste regras do ESLint conforme a sua equipe (ex.: permitir any em alguns casos, strenghten rules, etc).
• Considere adicionar GitHub Actions para rodar npm run lint e npx tsc --noEmit no CI.

Arquivos importantes para revisão

• package.json — scripts, dependências e hooks
• tsconfig.json — paths e jsx
• src/routes/index.tsx — ponto central de rotas (já convertido para template)
• src/features/api/apiSlice.ts — base para chamadas HTTP (RTK Query)
• src/store/store.ts — setup do Redux
• src/@types/index.d.ts — declare módulos sem tipos

Licença

Coloque aqui a licença do seu template (ex.: MIT) se for público.

Se quiser eu:

• 1. adapto esse README para uma versão curta em inglês;
• 2. gero instruções de CI (GitHub Actions) que rodem npm install, npm run lint e npx tsc --noEmit;
• 3. adiciono um script create-app simples que copia o template e roda um assistant de setup.

Diga qual das opções acima prefere que eu crie em seguida.

Nota sobre lockfile (recomendado)

Para builds reprodutíveis e para que o workflow npm ci funcione sem problemas, é recomendável commitar o package-lock.json no repositório. Porém, alguns ambientes (ou templates) não incluem o lockfile — por isso os workflows desse template utilizam npm install --legacy-peer-deps --no-audit --no-fund quando necessário, que é mais tolerante a ausência do lockfile e a conflitos de peer.

Se quiser garantir installs idempotentes em CI, gere o lockfile localmente e commite:

npm install --legacy-peer-deps
git add package-lock.json
git commit -m "chore: add package-lock.json"