Guia do Laravel React: Como construir e implantar um SPA moderno

Hoje em dia, os utilizadores da Web esperam que as aplicações sejam instantâneas e interactivas, comportando-se mais como aplicações móveis do que como websites tradicionais. Embora o Laravel seja uma estrutura de back-end robusta, sua renderização padrão do lado do servidor geralmente depende de recarregamentos de páginas inteiras, o que pode parecer desajeitado.

A solução é o React JS. Ao lidar com a interface diretamente no browser, o React elimina os constantes recarregamentos de página, fazendo com que cada clique e transição pareçam instantâneos.

A fusão destas duas tecnologias permite-te manter a segurança e a estrutura robustas de um backend Laravel, ao mesmo tempo que proporcionas uma experiência de utilizador rápida de uma aplicação de página única (SPA).

Neste blog, vou mostrar-te como integrar o React JS no Laravel. Começaremos criando um novo projeto em uma configuração local, configurando o frontend React e, finalmente, implantando-o em um servidor Cloudways pronto para produção.

Por que integrar React JS com Laravel?

Há dez anos, era normal que uma página Web se actualizasse completamente sempre que um utilizador clicava num botão como “Guardar”. O ecrã piscava, a página recarregava e os utilizadores aguardavam a resposta. Na altura, este comportamento era aceite como parte da utilização da Web.

Atualmente, as expectativas dos utilizadores são muito diferentes. Os utilizadores modernos esperam um feedback rápido, transições suaves e interfaces que respondam instantaneamente às suas acções. Espera-se agora que as aplicações Web sejam mais parecidas com as aplicações móveis do que com os sítios Web tradicionais.

A integração do React com o Laravel ajuda a obter essa experiência de maneira prática. O Laravel lida com as responsabilidades de back-end, como autenticação, autorização, operações de banco de dados, validação e lógica comercial. O React concentra-se no front-end, atualizando a interface do usuário dinamicamente sem forçar o navegador a recarregar páginas inteiras.

1. Experiência de aplicação de página única

Numa aplicação tradicional com renderização no servidor, cada navegação ou envio de formulário envia um pedido ao servidor e devolve uma página HTML completa. Embora esta abordagem seja fiável, muitas vezes parece lenta e interruptiva.

Quando o React é integrado ao Laravel, geralmente usando ferramentas como o Inertia.js, a aplicação carrega uma vez. Após esse carregamento inicial, a navegação acontece por meio da atualização de componentes em vez de recarregar as páginas. Isso resulta em transições mais rápidas e uma experiência geral mais suave para o usuário.

2. Reutilização de componentes

À medida que as aplicações crescem, as funcionalidades interactivas, como o carregamento de ficheiros, a validação em tempo real, os modais e os painéis de controlo, podem tornar-se difíceis de gerir quando construídas diretamente dentro de modelos PHP. A lógica torna-se frequentemente dispersa e difícil de manter.

O React incentiva a construção desses recursos como componentes independentes. Um carregador de arquivos, por exemplo, pode ser construído uma vez e reutilizado em toda a aplicação. Cada componente gerencia seu próprio estado e comportamento, o que mantém a base de código organizada e mais fácil de estender ao longo do tempo.

3. Acesso ao ecossistema de pacotes JavaScript

O React faz parte do ecossistema JavaScript mais amplo, que é suportado por um gerenciador de pacotes chamado NPM. O NPM é um repositório de pacotes JavaScript reutilizáveis que resolvem problemas comuns de desenvolvimento.

Estes pacotes incluem ferramentas para tabelas de dados, gráficos, tratamento de formulários, animações e muitas outras caraterísticas relacionadas com a interface. A maioria deles é de código aberto, mantida ativamente e amplamente usada em ambientes de produção. Ao usar o React, os desenvolvedores podem contar com essas soluções existentes em vez de construir tudo do zero.

4. Preparação para o desenvolvimento móvel

A utilização do React no frontend também torna o desenvolvimento móvel futuro mais simples. O React Native permite que os programadores reutilizem grande parte da sua lógica JavaScript para criar aplicações móveis nativas para iOS e Android.

O mesmo backend Laravel pode servir tanto a aplicação Web como as aplicações móveis através de APIs. Essa abordagem reduz a duplicação de esforços e facilita a manutenção de um comportamento consistente entre plataformas.

Para as equipas que constroem aplicações modernas, a combinação de React e Laravel proporciona um equilíbrio entre uma estrutura de back-end forte e um front-end reativo e fácil de utilizar.

Como integrar o React JS no Laravel

Neste tutorial, vamos nos concentrar na maneira mais eficiente de combinar essas tecnologias: a pilha Inertia.js. Essa abordagem permite que você crie um aplicativo moderno de página única usando o roteamento e os controladores clássicos do Laravel, mas com o React como sua camada de visualização de front-end.

O que vamos construir: Para mostrar-te esta integração, vamos construir uma Lista de Tarefas Reactiva. No final deste guia, terás uma aplicação funcional onde poderás ver as tarefas obtidas da tua base de dados Laravel e adicionar novas tarefas instantaneamente, tudo sem recarregar a página do browser.

Código fonte: Se tiveres dificuldades ou quiseres ver o resultado final, podes ver o projeto completo no meu Repositório GitHub.

Pré-requisitos para este tutorial

Antes de mergulharmos no código, certifica-te de que o teu ambiente de desenvolvimento está pronto. Precisarás das seguintes ferramentas instaladas para executar um aplicativo moderno do Laravel 11:

• PHP 8.2 ou superior: O Laravel 11 requer os recursos mais recentes do PHP para um desempenho ideal.
• Composer: O gerenciador de dependências padrão para PHP, usado para instalar o framework.
• Node.js & NPM (Crítico): Tens de ter o Node.js instalado para construir o frontend. Descarrega o instalador do Windows (.msi) aqui. Depois de instalares o Node.js, tens de fechar e reiniciar o teu Prompt de Comando para que as alterações tenham efeito.
• Uma base de dados: MySQL (ou MariaDB) é a escolha padrão, embora possas usar SQLite para testes locais rápidos.

Passo 1: Instala o projeto Laravel

• Primeiro, vamos criar uma nova instalação do Laravel.
• Abre o teu Prompt de Comando (CMD), navega até à pasta onde guardas os teus projectos (por exemplo, cd Desktop ou cd xampp/htdocs) e executa o seguinte comando:

compositor criar projeto laravel/laravel react-task-app

• Este comando descarrega a última versão do Laravel (atualmente a versão 11) e cria uma pasta chamada react-task-app.
• Quando a instalação estiver concluída, navega para a pasta do teu projeto:

cd react-task-app

Passo 2: Configura a base de dados

• Como estamos a criar uma lista de tarefas, precisamos de uma base de dados para armazenar as tarefas.
• Abre o Painel de Controlo XAMPP e certifica-te de que o Apache e o MySQL estão a funcionar.

• Vai para phpMyAdmin no teu browser (normalmente http://localhost/phpmyadmin).
• Clica em Novo na barra lateral.
• Dá à tua base de dados o nome react_task_app.
• Na lista pendente junto ao nome (Collation), seleciona utf8mb4_unicode_ci.
• Clica em Criar.

• Agora, liga esta base de dados ao teu projeto Laravel. Abre a pasta do projeto no teu editor de código (como o VS Code, notepad), encontra o ficheiro .env e actualiza as definições da base de dados:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=react_task_app
DB_USERNAME=root
DB_PASSWORD=

Aqui está uma captura de ecrã do meu ficheiro .env atualizado:

Passo 3: Instala o React através do Laravel Breeze

• Este é o passo mais crítico. No passado, os programadores tinham de instalar manualmente o React e configurar o Webpack. Hoje, usamos o Laravel Breeze, que configura automaticamente o React, o Vite e o Inertia.js para nós.

set PATH=%PATH%;C:\Users\abdulrehman\Downloads\node-v24.13.0-win-x64\node-v24.13.0-win-x64

• Agora que o Node está pronto, executa o seguinte comando no teu terminal para instalar o pacote Breeze:

compositor require laravel/breeze --dev

• Em seguida, executa o comando de instalação e seleciona a pilha React:

php artisan breeze:install react

• Depois que o scaffolding for instalado, precisamos garantir que os ativos do front-end sejam compilados. Executa os seguintes comandos para instalar as bibliotecas JavaScript e compilar os arquivos React:

instala o npm
npm run build

• Isto garante que, mesmo que tenhas uma configuração de ambiente personalizada, todas as dependências React necessárias são corretamente instaladas e construídas.

Passo 4: Executa as migrações

• Agora que ligámos a nossa base de dados no ficheiro .env, precisamos de criar as tabelas (como a tabela Users) para que o sistema de login funcione.
• Se ignorares este passo, encontrarás um erro“Tabela não encontrada” quando tentares visualizar a aplicação.
• Executa o seguinte comando:

php artisan migrate

Passo 5: Verifica a instalação

• Neste ponto, a tua instalação está concluída. Vamos verificar se funciona antes de começarmos a codificar a Lista de Tarefas.
• Inicia o servidor Laravel:

php artisan serve

• Abre o teu browser e visita: http://127.0.0.1:8000
• Deves ver a página inicial do Laravel. Olha para o canto superior direito: se vires as ligações “Log in” e “Register”, significa que integraste com sucesso o React com o Laravel.

Criar a lista de tarefas reactivas

Agora que nosso ambiente está pronto, vamos criar um aplicativo simples de “Lista de tarefas”. Isso demonstrará como passar dados do Laravel para o React e como enviar dados de volta do Laravel sem recarregar a página.

Passo 1: Cria o modelo e a migração

• Primeiro, precisamos de uma tabela de base de dados para armazenar as nossas tarefas. Em Laravel, usamos um“Modelo” para interagir com a base de dados.
• Executa este comando no teu terminal:

php artisan make:model Task -m

• (O sinalizador -m diz ao Laravel para também criar um arquivo de “migração” para a tabela do banco de dados).
• Agora, abre o ficheiro de migração recentemente criado, localizado em database/migrations/xxxx_xx_xx_create_tasks_table.php. Actualiza o método up() para incluir uma coluna para o título da tarefa:

função pública up(): void
{
  Schema::create('tasks', function (Blueprint $table) {
  $table->id();
  $table->string('title'); // Adiciona esta linha
  $table->booleano('is_completed')->default(false); // Opcional: para seguir a conclusão
  $table->timestamps();
  });
}

• Em seguida, abre o ficheiro Modelo em app/Models/Task.php.
• Substitui todo o conteúdo do arquivo pelo código abaixo. Isso garante que a caraterística“HasFactory” necessária seja importada corretamente:

<?php

namespace App\Models;

utiliza Illuminate\Database\Eloquent\Factories\HasFactory;
utiliza Illuminate\Database\Eloquent\Model;

classe Task extends Model
{
  utiliza HasFactory;

  protected $fillable = ['title', 'is_completed'];
}

• Por fim, executa a migração para criar a tabela na tua base de dados:

php artisan migrate

Passo 2: Cria o controlador

• Precisamos de um Controller para tratar da lógica – ir buscar tarefas à base de dados e guardar novas tarefas.
• Executa este comando:

php artisan make:controller TaskController

• Abre app/Http/Controllers/TaskController.php e cola o seguinte código. É aqui que a magia acontece: em vez de devolveres uma vista genérica, devolvemos um render Inertia.

<?php

namespace App\Http\Controllers;

utiliza App\Models\Task;
utiliza Illuminate\Http\Request;
usa Inertia\Inertia; // Importar Inércia

class TaskController extends Controller
{
  função pública index()
  {
  // Vai buscar todas as tarefas, ordenadas pela mais recente primeiro
  $tasks = Task::orderBy('id', 'desc')->obtém();

  // Renderiza o componente React chamado "Tasks/Index" e passa as tarefas como props
  devolve Inertia::render('Tasks/Index', [
  'tarefas' =>  $tarefas
  ]);
  }

  função pública store(Request $request)
  {
  // Valida a entrada
  $request->valida([
  'título' =>  'obrigatório|string|max:255'
  ]);

  // Cria a tarefa
  Task::create([
  'título' =>  $request->entra('título')
  ]);

  // Redirecciona de volta (a Inertia tratará da atualização sem um recarregamento completo)
  devolve redirect()->volta();
  }
}

Passo 3: Define as rotas

• Finalmente, precisamos de dizer ao Laravel para onde direcionar o tráfego. Abre routes/web.php e adiciona estas duas rotas:

utiliza App\Http\Controllers\TaskController;

// ... percursos existentes ...

Route::get('/tasks', [TaskController::class, 'index'])->nome('tarefas.índice');
Route::post('/tasks', [TaskController::class, 'store'])->nome('tasks.store');

• Eis o aspeto do meu ficheiro atualizado:

<?php

utiliza App\Http\Controllers\ProfileController;
utiliza App\Http\Controllers\TaskController;
utiliza Iluminar\Fundação\Aplicação;
usa Iluminate\Support\Facades\Route;
usa Inertia\Inertia;

Route::get('/', function () {
  Devolve Inertia::render('Welcome', [
  'canLogin' =>  Route::has('login'),
  'canRegister' =>  Route::has('register'),
  'laravelVersion' =>  Aplicação::VERSÃO,
  'phpVersion' =>  PHP_VERSION,
  ]);
});

Route::get('/dashboard', function () {
  Devolve Inertia::render('Dashboard');
})->middleware(['auth', 'verified'])->nome('dashboard');

Route::middleware('auth')->grupo(função () {
  Route::get('/profile', [ProfileController::class, 'edit'])->nome('perfil.editar');
  Route::patch('/profile', [ProfileController::class, 'update'])->nome('profile.update');
  Route::delete('/profile', [ProfileController::class, 'destroy'])->nome('profile.destroy');

  Route::get('/tasks', [TaskController::class, 'index'])
  ->nome('tarefas.índice');

  Route::post('/tasks', [TaskController::class, 'store'])
  ->nome('tasks.store');
});

requer __DIR__.'/auth.php';

Passo 4: Cria o Frontend React

Agora, vamos construir a interface. Quando retornamos Inertia::render('Tasks/Index') em nosso Controller, Inertia procurou por um arquivo localizado em resources/js/Pages/Tasks/Index.jsx.

Vamos criar esse ficheiro agora.

1. Cria o ficheiro de componentes

• Navega para resources/js/Pages.
• Cria uma nova pasta chamada Tarefas.
• Dentro dessa pasta, cria um ficheiro chamado Index.jsx.

2. Adiciona o código React

Cola o seguinte código no teu novo ficheiro. Este componente faz duas coisas:

1. Mostra as tarefas: Aceita o tasks prop do Laravel e mapeia-o para mostrar a lista.
2. Adiciona tarefas: Usa o gancho useForm da Inertia para lidar com o envio do formulário sem recarregar a página.

importa React de 'react';
import AuthenticatedLayout from '@/Layouts/AuthenticatedLayout'; // Usa o layout padrão do Breeze
importa { Head, useForm } de '@inertiajs/react';

export default function Index({ auth, tasks }) {
  // Nós usamos o gancho useForm para manipular os dados do formulário e o envio
  const { data, setData, post, processing, reset, errors } = useForm({
  título: '',
  });

  const submit = (e) =>  {
  e.preventDefault();
        
  // Envia um pedido POST para a rota Laravel chamada 'tasks.store'
  post(route('tasks.store'), {
  onSuccess: () =>  reset(), // Limpa o formulário em caso de sucesso
  });
  };

  devolve (
        <AuthenticatedLayout
  user={auth.user}
  cabeçalho={<h2 className="font-semibold text-xl text-gray-800 leading-tight">A minha lista de tarefas</h2>}
        >
            <Cabeçalho title="Tarefas" />

            <div className="py-12">
                <div className="max-w-7xl mx-auto sm:px-6 lg:px-8">
                    <div className="bg-white overflow-hidden shadow-sm sm:rounded-lg p-6">
                        
                         {/* O FORMULÁRIO */}
                        <formulário onSubmit={submit}  className="flex gap-4 mb-8">
                            <div className="flex-1">
                                <entrada
  tipo="texto"
  className="border-gray-300 focus:border-indigo-500 focus:ring-indigo-500 rounded-md shadow-sm w-full"
  placeholder="O que é que precisa de ser feito?"
  value={data.title}
  onChange={(e) =>  setData('title', e.target.value)}
 
/>
  {errors.title &&  <div className="text-red-500 text-sm mt-1">{Não te esqueças do título.}</div>}
                            </div>
                            <botão
  tipo="submeter"
  desativado={processing}
  className="bg-gray-800 text-white px-4 py-2 rounded-md hover:bg-gray-700 transition"
                            >
  Adicionar tarefa
                            </button>
                        </form>

                         {/* A LISTA DE TAREFAS */}
                        <div className="space-y-4">
  {tarefas.map((tarefa) =>  (
                                <div key={task.id} className="p-4 border border border-gray-200 rounded-lg flex items-center justify-between">
                                    <span className="text-gray-800">{tarefa.título}</span>
                                    <span className="text-xs text-gray-500">
  {new Date(task.created_at).toLocaleTimeString()}
                                    </span>
                                </div>
  ))}
  {tasks.length === 0 && (
                                <p className="text-gray-500 text-center">Ainda não tens tarefas. Adiciona uma acima! </p>
  )}
                        </div>

                    </div>
                </div>
            </div>
        </AuthenticatedLayout>
  );
}

3. Testa a aplicação

Agora chega o momento da verdade. Vamos ver a tua aplicação em ação.

• Compila seus ativos: Como acabamos de criar um novo componente React, precisamos dizer ao Vite para incluí-lo. Executa o comando de compilação uma última vez:

npm run build

• Inicia o servidor: Certifica-te de que o teu servidor Laravel está a funcionar:

php artisan serve

• Inicia a sessão: Abre o teu browser em http://127.0.0.1:8000. Como esta é uma base de dados nova, clica em Registar para criar uma nova conta.

• Visita a Lista de Tarefas: Uma vez iniciada a sessão, altera manualmente o URL na tua barra de endereços para:

http://127.0.0.1:8000/tasks

Deves ver a tua nova página “A minha lista de tarefas”.

Experimenta: Escreve o nome de uma tarefa e carrega em“Adicionar tarefa“. Verás que a tarefa aparece instantaneamente na lista. O formulário é limpo, a lista é actualizada e a página não é recarregada.

E é isso! Construímos com sucesso uma aplicação reativa de página única (SPA) usando Laravel e React.

Implementar a tua aplicação React na Cloudways

Nesta secção final, vamos mover a nossa aplicação Reactive Task List para um ambiente de produção.

Usaremos o Git para enviar nosso código para um repositório central e, em seguida, conectaremos um servidor Cloudways para extrair esse código automaticamente. Este fluxo de trabalho é o padrão da indústria para o desenvolvimento moderno da web.

1. Prepara o teu repositório local

Primeiro, temos de converter a pasta do teu projeto num repositório Git. Isto permite-nos seguir as alterações e sincronizá-las com o servidor.

Abre o teu terminal dentro da pasta react-task-app e executa estes comandos:

# Initialize Git
git init

# Stage all files
git add .

# Commit your changes
git commit -m "Initial launch of React Task App"

# Rename branch to main
git branch -M main

2. Envia para o GitHub

Agora, vamos criar uma casa remota para o teu código.

• Faz login no GitHub e cria um Novo Repositório.
• Dá-lhe o nome de react-task-app e clica em Criar.

O GitHub fornecerá um conjunto de comandos para fazer push do teu repositório existente. Copia os comandos que se parecem com isto:

git remote add origin https://github.com/YOUR_USERNAME/react-task-app.git
git push -u origin main

Corre-os no teu terminal, um a um.

Quando o push estiver concluído, atualiza a página do GitHub. Deves ver os ficheiros do teu projeto listados.

3. Aprovisiona o servidor

Se ainda não tiveres um servidor, inicia um na Cloudways, inscrevendo-te para uma avaliação gratuita de 3 dias. Selecione Laravel como seu tipo de aplicativo e nomeie-o como TaskApp.

4. Autoriza a Cloudways via SSH

Por segurança, usaremos uma chave SSH para permitir que o Cloudways fale com o GitHub. Isso é mais seguro do que usar senhas.

• Na Cloudways, vai a Aplicações → TaskApp → Implementação via Git.

• Clica em Gerar chaves SSH e depois em Ver chave SSH. Copia a chave.

• Vai ao teu Repositório GitHub → Definições → Chaves de implementação.
• Clica em Adicionar chave de implementação, cola a chave, dá-lhe um título e guarda.

5. Implementa a base de código

Com a permissão definida, podemos agora puxar o código.

• No GitHub, clica no botão verde Código e copia o URL SSH (começa com [email protected]...).

• De volta ao Cloudways, cola isso no campo Endereço remoto do Git.
• Clica em Autenticar.

• Seleciona o ramo main e clica em Start Deployment.

A Cloudways irá agora clonar o teu repositório para o servidor.

6. Constrói os activos e configura a base de dados

Este é o passo mais crítico para aplicações React. Ao contrário de um site PHP padrão, precisamos compilar nossos ativos JavaScript no servidor ou o front-end não será carregado.

A. Acede ao terminal do servidor

Vai para o separador Master Credentials na Cloudways e abre o Terminal SSH. Faz login com suas credenciais.

B. Navegar para a tua aplicação

Procura o nome da tua base de dados no separador Detalhes do Access (por exemplo, qxyrz...). Em seguida, na janela do terminal SSH, navega para a pasta da tua aplicação, executando o comando abaixo:

cd applications/[YOUR_DB_NAME]/public_html

C. Instalar e compilar (o passo React)

Importante: antes de executar os comandos de instalação, vai para as configurações do aplicativo Cloudways e clica em Redefinir permissões. Isso evita erros de “Permissão negada” durante a instalação.

Executa os três comandos a seguir em ordem. Isso instala as bibliotecas de back-end, as bibliotecas de front-end e, em seguida, cria os arquivos React de produção.

instala o compositor
instala o npm
npm run build

Nota: O comando npm run build é o que converte o teu código React nos ficheiros estáticos de que o browser necessita.

D. Finaliza a ligação à base de dados

Primeiro, precisamos limpar os arquivos de migração padrão do Cloudways que entram em conflito com o Laravel 11. Executa este comando para evitar erros dotipo “Table already exists“:

rm database/migrations/2014_*.php database/migrations/2019_*.php

Em seguida, actualiza o ficheiro .env com as credenciais da base de dados em tempo real que se encontram no separador Detalhes do acesso.

nano .env

Actualiza DB_DATABASE, DB_USERNAME, e DB_PASSWORD. Guarda o ficheiro (Ctrl+X, Y, Enter).

Em seguida, executa a migração para criar a tua tabela de tarefas:

php artisan migrate:fresh --force

7. Entra em direto

Neste ponto, a tua implementação está completa. Vá em frente e abra a URL do seu aplicativo Cloudways e clique no link Registrar no canto superior direito do seu site.

Cria uma nova conta e, uma vez registado, adiciona /tasks ao final do URL da tua aplicação. Deves ver a tua aplicação reactiva e totalmente funcional a ser executada no servidor em tempo real.

Aqui está ele em ação no servidor ao vivo:

E aqui estão os dados que estão a ser guardados na base de dados da Cloudways:

Conclusão

Conseguiste colmatar a lacuna entre um backend robusto e um frontend dinâmico. Ao integrar Laravel e React usando Inertia.js, evitaste a complexidade de criar uma API separada, mantendo o teu fluxo de trabalho de desenvolvimento simples e eficiente.

Neste guia, tu passaste de um quadro em branco para um aplicativo“Lista de tarefas” totalmente funcional. Configuraste um ambiente local moderno, construíste uma interface reativa que se atualiza instantaneamente sem recarregar a página e implantaste o resultado final em um servidor Cloudways pronto para produção.

Se quiseres rever o código ou usar este projeto como ponto de partida, podes encontrar o código fonte completo no meu Repositório GitHub.

Esta configuração – Laravel para a lógica, React para a interface e Cloudways para o alojamento – dá-te uma base escalável. Quer estejas a construir ferramentas internas, projectos de clientes, ou a próxima grande plataforma SaaS, tens agora a arquitetura para o fazer acontecer.

Abdul Rehman

O Abdul é um profissional de marketing experiente em tecnologia, movido a café e criativo, que adora manter-se a par das últimas actualizações de software e gadgets tecnológicos. É também um escritor técnico competente que consegue explicar conceitos complexos de forma simples para um público alargado. Abdul gosta de partilhar os seus conhecimentos sobre a indústria da nuvem através de manuais de utilizador, documentação e publicações em blogues.

Get Connected on: Twitter Community Forum