Como incluir JavaScript no Laravel 11: um guia passo a passo para todos os cenários

No Laravel 11, adicionar JavaScript ao seu projeto pode ser muito fácil, graças ao Vite, o empacotador de ativos padrão. Veja como configurar seu JavaScript para todos os tipos de cenários, desde a inclusão global até o carregamento condicional em visualizações específicas.

1. Incluindo JavaScript em todos os arquivos

Em muitos casos, você pode querer incluir JavaScript globalmente em seu aplicativo Laravel. Veja como organizar e agrupar JavaScript para inclusão universal.

Etapa 1: coloque seu arquivo JavaScript

1. Local: Armazene arquivos JavaScript no diretório resources/js. Por exemplo, se o nome do seu arquivo for custom.js, salve-o como resources/js/custom.js.
2. Organizar: para projetos complexos com vários arquivos JavaScript, você pode organizá-los em subdiretórios em resources/js, como resources/js/modules/custom.js.

Etapa 2: compilar JavaScript com Vite

Laravel 11 usa Vite para gerenciar ativos. Para configurá-lo para agrupar seu JavaScript:

1. Incluir em app.js: Abra resources/js/app.js e importe seu arquivo personalizado:

   import './custom.js';

1. Importação Direta em Views: Como alternativa, se você deseja apenas o JavaScript em determinadas visualizações, você pode usar a diretiva @vite no modelo Blade:

   @vite('resources/js/custom.js')

Etapa 3: configurar vite.config.js

Certifique-se de que vite.config.js esteja configurado para lidar com as importações @vite corretamente. Por padrão, deve ser algo assim:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/js/app.js'],
            refresh: true,
        }),
    ],
});

Etapa 4: execute o Vite

Para compilar seus ativos com Vite:

• Para desenvolvimento: execute npm run dev
• Para produção: execute npm run build

Etapa 5: carregar JavaScript em modelos Blade

Para incluir arquivos JavaScript em seus modelos, use a diretiva @vite:

    
    @vite('resources/js/app.js')


    

Resumo

• Armazene arquivos JavaScript em resources/js.
• Importe em app.js para inclusão global ou inclua diretamente em modelos Blade conforme necessário.
• Compile ativos usando o Vite.
• Use @vite em modelos Blade para carregar JavaScript.

Com esta configuração, o JavaScript estará disponível em todo o site em um projeto Laravel 11.

2. Compreendendo a ordem de renderização das lâminas

Ao incluir JavaScript condicionalmente em visualizações específicas, é essencial entender a ordem em que os modelos Blade são renderizados.

No Laravel, layouts são processados ​​primeiro, seguidos por visualizações individuais e parciais. Aqui está o processo de renderização:

1. O layout é renderizado primeiro, com espaços reservados (@yield e @section) criados para injeção de conteúdo.
2. Visualizações secundárias ou parciais são processadas em seguida, com seu conteúdo inserido nos espaços reservados do layout.

Devido a esta ordem, se você quiser adicionar condicionalmente arquivos JavaScript no layout com base no conteúdo da visualização secundária, as verificações de variáveis ​​padrão não funcionarão. Você precisará usar as diretivas @stack e @push do Blade para um tratamento mais flexível de JavaScript específico da página.

3. Incluindo JavaScript condicionalmente em visualizações específicas usando Stack e Push

Para adicionar JavaScript a visualizações específicas, as diretivas @stack e @push do Laravel oferecem uma solução eficiente, permitindo incluir scripts condicionalmente no layout.

Etapa 1: Defina uma pilha em seu layout

No seu layout, crie uma pilha para scripts específicos da página:

    
    @vite('resources/js/app.js')
    @stack('scripts') 


    @yield('content')

Etapa 2: enviar scripts de visualizações secundárias

No arquivo Blade específico que precisa do JavaScript, envie para a pilha de scripts:

@extends('layout')

@section('content')
    
@endsection

@push('scripts')
    @vite('resources/js/custom.js')
@endpush

Com esta configuração, custom.js só será incluído quando aquela visualização específica for carregada. Este método fornece uma solução limpa que funciona com a ordem de renderização do Laravel, garantindo que os arquivos JavaScript sejam incluídos condicionalmente conforme necessário.

Onde declarar @push?

A colocação de instruções @push em uma visualização Blade é importante principalmente para legibilidade e ordem de execução. Veja como usar @push de forma eficaz:

1. Colocação na visualização: Embora você possa colocar @push em qualquer lugar em uma visualização Blade, é uma prática recomendada colocá-lo no final do arquivo, geralmente após o conteúdo da @section. Isso mantém o código relacionado ao script separado do conteúdo principal, melhorando a legibilidade e a manutenção.

   @extends('layout')

   @section('content')
       
   @endsection

   @push('scripts')
       @vite('resources/js/custom.js')
   @endpush

1. Ordem de múltiplas instruções @push: Se você tiver múltiplas declarações @push para a mesma pilha (por exemplo, @push('scripts')), elas serão anexadas na ordem em que aparecem na visualização. Por exemplo:

   @push('scripts')
       
   @endpush

   @push('scripts')
       
   @endpush

Nesse caso, script1.js será carregado antes de script2.js porque @push adiciona conteúdo à pilha na ordem em que foi declarado.

1. Usando @push em parciais e componentes: @push também pode ser usado em parciais do Blade (por exemplo, @include) ou componentes do Blade. Isso é útil para incluir scripts ou estilos específicos de visualização diretamente em componentes reutilizáveis, facilitando o gerenciamento de dependências.

   
   

       
   

   @push('scripts')
       @vite('resources/js/partial-specific.js')
   @endpush

Quando este parcial é incluído em uma visualização, parcial-specific.js será adicionado à pilha de scripts no arquivo de layout.

1. Controle o pedido com @prepend: Se scripts específicos precisarem ser carregados antes de outros na mesma pilha, você pode usar @prepend em vez de @push. @prepend coloca o conteúdo no início da pilha, permitindo maior controle sobre a ordem de carregamento.

   @prepend('scripts')
       
   @endprepend

   @push('scripts')
       
   @endpush

Aqui, critic.js será carregado antes de non_critical.js, independentemente de seu posicionamento no arquivo Blade.

Principais conclusões

• Coloque @push no final das visualizações para maior clareza e facilidade de manutenção.
• Ordem é determinado pelo posicionamento na visualização, com instruções @push anteriores sendo carregadas primeiro.
• @push funciona em parciais e componentes, facilitando a inclusão de dependências específicas da visualização.
• Use @prepend para scripts que precisam ser carregados primeiro na mesma pilha.

4. Alternativa: Usando declarações condicionais embutidas no layout

Se você precisar de um controle mais preciso sobre quando o JavaScript é incluído, as instruções condicionais do Laravel permitem lógica baseada em rota ou variável diretamente no layout.

Incluir condicionalmente com base na rota

Você pode usar verificações de rota diretamente no layout para incluir JavaScript com base na rota atual:

@if (request()->routeIs('some.route.name'))
    @vite('resources/js/custom.js')
@endif

Incluir condicionalmente com base em uma variável

Para carregar scripts condicionalmente com base em variáveis, você pode definir um sinalizador no controlador ou na visualização filha e, em seguida, verificá-lo no layout:

1. No seu controlador:

   return view('your.view', ['loadCustomJS' => true]);

1. No layout:

   @if (!empty($loadCustomJS))
       @vite('resources/js/custom.js')
   @endif

Essa abordagem permite controlar o carregamento do JavaScript com base em variáveis ​​ou rotas específicas, proporcionando flexibilidade para configurações de páginas personalizadas.

Resumo

Aqui está uma rápida visão geral dos métodos discutidos:

• Inclusão global: coloque JavaScript em app.js e inclua-o globalmente usando @vite.
• Inclusão condicional com Stack e Push: Use as diretivas @stack e @push para manipulação flexível e modular de scripts, o que garante que os scripts sejam carregados apenas nas visualizações onde são necessários.
• Declarações condicionais no layout: Use verificações baseadas em rota ou variáveis ​​de controlador para carregar condicionalmente o JavaScript diretamente no layout.

Essas opções permitem que você controle o carregamento do JavaScript com precisão, tornando seu projeto Laravel 11 eficiente e fácil de manter.