Configurar React hoje não é mais sair dando npx create-react-app igual antigamente.

Esse trem já ficou pra museu. Hoje o caminho profissional é:

• Node.js LTS

• NVM para controlar versões

• Vite para criar o projeto

• TypeScript

• ESLint e Prettier

• Tailwind CSS

• VS Code bem configurado

A própria documentação do React recomenda usar uma ferramenta de build como Vite, Parcel ou Rsbuild para criar uma aplicação do zero, e o Vite exige Node.js 20.19+ ou 22.12+ nas versões atuais.

1. Instalar o Node.js do jeito certo

A forma mais limpa é usar NVM, porque projeto React vive mudando versão de Node. Instalar Node direto no sistema funciona, mas depois vira aquele samba do node_modules.

macOS / Linux

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

Depois reinicie o terminal e rode:

nvm --version

Instale a versão LTS:

nvm install --lts
nvm use --lts

Verifique:

node -v
npm -v

Windows

No Windows, use o nvm-windows.

Depois de instalar:

nvm list available
nvm install 24
nvm use 24

O Node.js atualmente mostra a linha v24 como Latest LTS, enquanto a linha v25 aparece como Current. Para projeto profissional, vai de LTS. Modinha em runtime é bonito até quebrar deploy sexta-feira.

2. Criar o projeto React com Vite

Agora vamos criar um projeto moderno com React + TypeScript.

npm create vite@latest nexucode-react-app -- --template react-ts

Entre na pasta:

cd nexucode-react-app

Instale as dependências:

npm install

Rode o projeto:

npm run dev

O Vite é hoje uma das ferramentas principais para frontend moderno, com servidor de desenvolvimento rápido, HMR e build otimizado.

3. Estrutura inicial do projeto

Depois de criar, você vai ver algo assim:

nexucode-react-app/
├── public/
├── src/
│   ├── assets/
│   ├── App.tsx
│   ├── main.tsx
│   └── index.css
├── index.html
├── package.json
├── tsconfig.json
└── vite.config.ts

Agora vamos deixar isso com cara de projeto profissional:

src/
├── app/
│   ├── routes/
│   └── providers/
├── assets/
├── components/
│   ├── ui/
│   └── layout/
├── features/
│   └── users/
├── hooks/
├── lib/
├── pages/
├── services/
├── styles/
├── types/
├── App.tsx
└── main.tsx

Essa organização evita aquele clássico projeto React que começa bonito e termina parecendo gaveta de cabo velho.

4. Configurar alias de importação

Instale os tipos do Node:

npm install -D @types/node

Edite o vite.config.ts:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'node:path'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
})

Agora ajuste o tsconfig.app.json:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Uso:

import { Button } from '@/components/ui/button'

Bem melhor do que:

import { Button } from '../../../../components/ui/button'

5. Instalar e configurar Tailwind CSS

Instale:

npm install tailwindcss @tailwindcss/vite

Atualize o vite.config.ts:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
import path from 'node:path'

export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
})

No src/index.css:

@import "tailwindcss";

Teste no App.tsx:

export default function App() {
  return (
    <main className="min-h-screen bg-slate-950 text-white flex items-center justify-center">
      <div className="rounded-2xl border border-slate-800 bg-slate-900 p-8 shadow-xl">
        <h1 className="text-3xl font-bold">React configurado com sucesso</h1>
        <p className="mt-3 text-slate-400">
          Ambiente pronto com Vite, TypeScript e Tailwind CSS.
        </p>
      </div>
    </main>
  )
}

6. Instalar ESLint e Prettier

O Vite já vem com ESLint em muitos templates, mas vamos deixar mais redondo.

npm install -D prettier eslint-config-prettier eslint-plugin-react-hooks eslint-plugin-react-refresh

Crie .prettierrc:

{
  "semi": false,
  "singleQuote": true,
  "printWidth": 90,
  "tabWidth": 2,
  "trailingComma": "all"
}

Crie .prettierignore:

node_modules
dist
build
coverage

No package.json, deixe scripts úteis:

{
  "scripts": {
    "dev": "vite",
    "build": "tsc -b && vite build",
    "preview": "vite preview",
    "lint": "eslint .",
    "format": "prettier --write ."
  }
}

Rodar:

npm run lint
npm run format

7. Configurar VS Code

Instale estas extensões:

ESLint
Prettier - Code formatter
Tailwind CSS IntelliSense
Error Lens
Auto Rename Tag
GitLens

Crie a pasta:

.vscode/

Crie .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "typescript.preferences.importModuleSpecifier": "non-relative",
  "tailwindCSS.experimental.classRegex": [
    ["cn\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"]
  ]
}

8. Criar configuração de ambiente .env

Crie:

.env

Exemplo:

VITE_API_URL=http://localhost:8080/api/v1
VITE_APP_NAME=NexuCodePlay

No código:

export const env = {
  apiUrl: import.meta.env.VITE_API_URL,
  appName: import.meta.env.VITE_APP_NAME,
}

Arquivo:

src/lib/env.ts

export const env = {
  apiUrl: import.meta.env.VITE_API_URL as string,
  appName: import.meta.env.VITE_APP_NAME as string,
}

Uso:

console.log(env.apiUrl)

No Vite, variáveis expostas ao frontend precisam começar com VITE_. Isso evita expor coisa sensível sem querer. Frontend não é cofre, é vitrine.

9. Instalar Axios

npm install axios

Crie:

src/services/api.ts

import axios from 'axios'
import { env } from '@/lib/env'

export const api = axios.create({
  baseURL: env.apiUrl,
  headers: {
    'Content-Type': 'application/json',
  },
})

Exemplo de serviço:

src/features/users/services/user-service.ts

import { api } from '@/services/api'

export interface User {
  id: number
  name: string
  email: string
}

export async function getUsers(): Promise<User[]> {
  const response = await api.get<User[]>('/users')
  return response.data
}

10. Instalar React Router

npm install react-router-dom

Crie:

src/app/routes/AppRoutes.tsx

import { BrowserRouter, Route, Routes } from 'react-router-dom'
import { HomePage } from '@/pages/HomePage'
import { AboutPage } from '@/pages/AboutPage'

export function AppRoutes() {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/" element={<HomePage />} />
        <Route path="/sobre" element={<AboutPage />} />
      </Routes>
    </BrowserRouter>
  )
}

Crie:

src/pages/HomePage.tsx

export function HomePage() {
  return <h1>Home</h1>
}

Crie:

src/pages/AboutPage.tsx

export function AboutPage() {
  return <h1>Sobre</h1>
}

Atualize o App.tsx:

import { AppRoutes } from '@/app/routes/AppRoutes'

export default function App() {
  return <AppRoutes />
}

11. Instalar biblioteca de ícones

npm install lucide-react

Exemplo:

import { Code2 } from 'lucide-react'

export function Logo() {
  return (
    <div className="flex items-center gap-2 font-bold">
      <Code2 className="h-5 w-5" />
      NexuCodePlay
    </div>
  )
}

12. Criar componente de layout

src/components/layout/AppLayout.tsx

import { ReactNode } from 'react'
import { Logo } from '@/components/layout/Logo'

interface AppLayoutProps {
  children: ReactNode
}

export function AppLayout({ children }: AppLayoutProps) {
  return (
    <div className="min-h-screen bg-slate-950 text-white">
      <header className="border-b border-slate-800">
        <div className="mx-auto flex max-w-6xl items-center justify-between px-4 py-4">
          <Logo />
          <nav className="flex gap-4 text-sm text-slate-300">
            <a href="/">Home</a>
            <a href="/sobre">Sobre</a>
          </nav>
        </div>
      </header>

      <main className="mx-auto max-w-6xl px-4 py-10">{children}</main>
    </div>
  )
}

Uso:

import { AppLayout } from '@/components/layout/AppLayout'

export function HomePage() {
  return (
    <AppLayout>
      <h1 className="text-3xl font-bold">Ambiente React Profissional</h1>
    </AppLayout>
  )
}

13. Comandos essenciais

npm run dev
npm run build
npm run preview
npm run lint
npm run format

Limpar dependências:

rm -rf node_modules package-lock.json
npm install

No Windows PowerShell:

Remove-Item -Recurse -Force node_modules
Remove-Item package-lock.json
npm install

14. Erros comuns

Erro: npm não é reconhecido

Node não foi instalado corretamente ou PATH não foi carregado.

Teste:

node -v
npm -v

Erro: versão do Node incompatível

Instale uma LTS atual:

nvm install --lts
nvm use --lts

Erro: alias @ não funciona

Confira se configurou:

vite.config.ts
tsconfig.app.json

Os dois precisam estar certos.

Tela branca

Veja o console do navegador. Geralmente é:

• import quebrado

• rota errada

• variável .env ausente

• componente exportado errado

Tailwind não aplica classe

Confira se o src/index.css tem:

@import "tailwindcss";

E se o arquivo CSS está importado no main.tsx:

import './index.css'

15. Estrutura final recomendada

src/
├── app/
│   ├── providers/
│   └── routes/
│       └── AppRoutes.tsx
├── assets/
├── components/
│   ├── layout/
│   │   ├── AppLayout.tsx
│   │   └── Logo.tsx
│   └── ui/
├── features/
│   └── users/
│       └── services/
│           └── user-service.ts
├── hooks/
├── lib/
│   └── env.ts
├── pages/
│   ├── AboutPage.tsx
│   └── HomePage.tsx
├── services/
│   └── api.ts
├── styles/
├── types/
├── App.tsx
├── index.css
└── main.tsx

Conclusão

React bem configurado não começa pelo componente bonito.

Começa pelo ambiente certo.

Com Node LTS, Vite, TypeScript, Tailwind, ESLint, Prettier e uma estrutura organizada, você já sai na frente de metade dos projetos que nascem bagunçados.

O frontend agradece. O deploy também.