Laravel Head

번역일: 2026년 8월 4일

Laravel Head

소개
설치
빠른 시작
메타데이터 우선순위
메타데이터 정의
Open Graph
- X / Twitter 카드
테마 색상
앱 메타데이터 및 아이콘
프로그레시브 웹 앱
성능 및 검색 엔진 최적화
커스텀 태그
스키마
렌더링
- Blade
- Livewire
- Inertia

소개

Laravel Head는 문서의 <head> 요소를 유창하게(fluent) 관리할 수 있는 API를 제공합니다. 타이틀 및 메타 태그, Open Graph 메타데이터, 정규(canonical) URL, 검색 로봇 지시자(robots directives), 성능 힌트, 구조화된 데이터(structured data) 등을 한곳에서 다룰 수 있습니다. Blade, Livewire, Inertia 모두 지원합니다.

설치

Composer로 Laravel Head를 설치합니다:

composer require laravel/head

빠른 시작

서비스 프로바이더에서 사이트 전체에 적용할 기본값을 등록합니다:

use Laravel\Head\Facades\Head;
use Laravel\Head\HeadBuilder;

Head::defaults(fn (HeadBuilder $head) => $head
    ->title('Laravel', suffix: ' - Laravel')
    ->description('무언가 훌륭한 것을 만들어 보세요.'));

특정 페이지에만 적용할 메타데이터는 런타임에 설정합니다:

Head::title($post->title)
    ->description($post->description);

레이아웃 파일에서 최종 태그를 렌더링합니다:

<head>
    @head
</head>

메타데이터 우선순위

페이지 메타데이터는 아래 다섯 레이어에서 낮은 우선순위 순으로 결정됩니다:

페이지 기본값 (Defaults)
라우트 그룹 메타데이터
라우트 메타데이터
런타임 메타데이터
에러 메타데이터

우선순위가 높은 레이어는 낮은 레이어의 값을 필드 단위로 덮어씁니다. 예를 들어, 런타임에서 타이틀만 지정하면 라우트의 description은 그대로 유지됩니다. 각 레이어에서 메타데이터를 설정하는 방법은 아래 섹션에서 설명하며, Blade·Livewire·Inertia에서 렌더링하는 방법은 렌더링 섹션을 참고하세요.

메타데이터 정의

Laravel Head는 사이트 전체 기본값, 라우트 메타데이터, 런타임 호출, 에러 페이지 정의 등 다양한 방식으로 메타데이터를 정의할 수 있습니다.

기본값

서비스 프로바이더에서 페이지 기본값을 등록합니다:

use Laravel\Head\Enums\OgType;
use Laravel\Head\Facades\Head;
use Laravel\Head\HeadBuilder;

Head::defaults(function (HeadBuilder $head) {
    $head
        ->title('Laravel', suffix: ' - Laravel')
        ->description('무언가 훌륭한 것을 만들어 보세요.')
        ->canonical()
        ->og(siteName: 'Laravel', type: OgType::Website)
        ->searchableByRobots()
        ->preconnect('https://fonts.example.com');
});

기본값은 가장 낮은 우선순위를 가집니다. 상위 레이어에서 타이틀을 지정하지 않으면 Laravel이 그대로 출력되고, 상위 레이어에서 타이틀을 지정하면 상속된 suffix가 자동 적용되어 Head::title('소개') → 소개 - Laravel로 렌더링됩니다. 상속된 prefix/suffix를 무시하려면 exact: true를 전달하세요.

Head::canonical()을 호출하면 현재 요청 URL을 정규 URL로 렌더링합니다. 특정 URL을 직접 지정하려면 Head::canonical('/about')처럼 문자열을 전달하세요. 정규 URL은 기본적으로 https로 정규화됩니다. 요청 스킴(scheme)을 그대로 유지하려면 forceHttps: false를 전달하세요.

로봇 지시자는 원시 문자열, RobotsRule 열거형(enum), 또는 두 형식을 혼합한 배열로 전달할 수 있습니다. 배열은 쉼표로 구분된 지시자로 렌더링되므로, Head::robots([RobotsRule::NoIndex, RobotsRule::NoFollow])는 noindex, nofollow로 출력됩니다.

편의 메서드로, searchableByRobots()는 all을, hiddenFromRobots()는 none을 렌더링합니다.

라우트 메타데이터

메타데이터가 미리 알려진 반정적(semi-static) 페이지의 경우 라우트에 직접 메타데이터를 정의할 수 있습니다.

라우트와 그룹

Route::view('/contact', 'contact')
    ->name('contact')
    ->withHead(
        title: '문의하기',
        description: '저희에게 연락해 주세요.',
    );

라우트 그룹에 공통 메타데이터를 적용할 수도 있습니다:

Route::withHead(robots: 'noindex, nofollow')
    ->prefix('admin')
    ->name('admin.')
    ->group(function () {
        Route::get('/dashboard', DashboardController::class)
            ->name('dashboard')
            ->withHead(title: '대시보드');
    });

리소스 및 싱글턴 라우트에도 메타데이터를 정의할 수 있습니다:

Route::resource('posts', PostController::class)->withHead(
    robots: 'index, follow',
);

Route::singleton('profile', ProfileController::class)->withHead(
    title: '내 프로필',
);

withHead 메서드는 Laravel의 기본 라우트 메타데이터 API를 통해 일반 배열로 저장하므로, 라우트 캐싱과 완전히 호환됩니다. 이는 head 키 아래에 속성을 중첩하여 metadata 메서드를 호출하는 것과 동일합니다.

named 인수는 에디터와 정적 분석 도구가 오타를 잡을 수 있도록 Laravel Head의 내장 라우트 속성으로 제한됩니다. 커스텀 태그 빌더로 등록된 라우트 속성은 extensions를 통해 전달할 수 있습니다:

Route::get('/article', ArticleController::class)->withHead(
    title: '아티클',
    extensions: ['readingTime' => 4],
);

지원 속성

라우트에서 지원하는 속성은 유창한(fluent) 빌더 메서드 이름과 동일하게 매핑됩니다:

카테고리	속성
문서	`title`, `description`, `canonical`, `robots`
앱 메타데이터	`themeColor`, `applicationName`, `colorScheme`, `referrer`, `viewport`, `appleWebAppTitle`, `webAppCapable`, `appleWebAppStatusBarStyle`
소셜	`og`, `ogImage`, `ogVideo`, `ogAudio`, `twitter`, `twitterImage`
성능	`preload`, `prefetch`, `preconnect`, `dnsPrefetch`
검색/탐색	`alternates`, `feed`, `icon`, `favicon`, `appleTouchIcon`, `appleTouchStartupImage`, `maskIcon`, `manifest`
구조화된 데이터	`schema`
커스텀 태그	`meta`, `link`

중첩 옵션명은 forceHttps, siteName, secureUrl처럼 유창한 API와 동일한 camelCase 명명 규칙을 따릅니다.

ogImage, preload, feed, schema, icon, appleTouchStartupImage처럼 반복 가능한 속성은 단일 값이나 배열 모두 허용합니다.

런타임 메타데이터

게시글 제목처럼 요청이 들어올 때까지 값을 알 수 없는 경우 런타임에 설정합니다:

use Laravel\Head\Facades\Head;

public function __invoke(Post $post): Response
{
    Head::title($post->title);

    // ...
}

Head 파사드를 통한 런타임 호출은 라우트 메타데이터를 덮어씁니다. 컨트롤러나 액션 메서드가 가장 일반적인 호출 위치입니다:

use App\Models\Post;
use Laravel\Head\Facades\Head;

public function show(Post $post)
{
    Head::title($post->title)
        ->description($post->description);

    return view('posts.show', ['post' => $post]);
}

여러 런타임 호출은 실행 순서대로 병합됩니다. 타이틀, description, 정규 URL, 로봇 지시자처럼 단일 값 필드는 나중에 호출한 값이 우선합니다. 반복 가능한 필드는 여러 항목을 유지하되, 동일한 키로 다시 추가하면 이전 항목이 갱신됩니다. ogImage의 경우 URL이 키입니다:

Head::ogImage('/images/cover.jpg', alt: '초안 커버')
    ->ogImage('/images/gallery.jpg', alt: '갤러리 이미지')
    ->ogImage('/images/cover.jpg', alt: '최종 커버', width: 1200, height: 630);

<meta property="og:image" content="/images/cover.jpg">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:alt" content="최종 커버">
<meta property="og:image" content="/images/gallery.jpg">
<meta property="og:image:alt" content="갤러리 이미지">

기본값에서 상속된 Open Graph 미디어는 폴백(fallback)으로 작동합니다. 라우트·런타임·에러 메타데이터에서 동일한 타입의 미디어를 정의하면 기본 미디어는 병합되지 않고 대체됩니다. 즉, 페이지의 og:image가 사이트 전체 기본 이미지보다 우선합니다.

when과 unless 메서드를 사용해 조건부 메타데이터를 유창하게 정의할 수 있습니다:

Head::title($post->title)
    ->when($post->isDraft(), fn ($head) => $head->hiddenFromRobots());

에러 페이지

에러 메타데이터는 일반적으로 AppServiceProvider의 boot 메서드에서 등록합니다:

use Laravel\Head\ErrorPages;
use Laravel\Head\Facades\Head;

/**
 * 애플리케이션 서비스를 부트스트랩합니다.
 */
public function boot(): void
{
    Head::errors(function (ErrorPages $errors) {
        $errors->defaults(robots: 'noindex, follow');

        $errors->status(
            404,
            title: '페이지를 찾을 수 없습니다',
            description: '요청하신 페이지를 찾을 수 없습니다.',
        );
    });
}

defaults와 status 메서드는 Head::defaults()에서 사용하는 것과 동일한 유창한 빌더 콜백도 허용합니다:

use Laravel\Head\ErrorPages;
use Laravel\Head\Facades\Head;
use Laravel\Head\HeadBuilder;

Head::errors(function (ErrorPages $errors) {
    $errors->status(404, fn (HeadBuilder $head) => $head
        ->title('페이지를 찾을 수 없습니다')
        ->description('요청하신 페이지를 찾을 수 없습니다.'));
});

등록된 에러 상태에 대한 응답이 렌더링되면 해당 메타데이터가 모든 다른 레이어보다 우선 적용됩니다.

Laravel은 에러 뷰를 렌더링하거나 Inertia의 handleExceptionsUsing() 같은 응답 단계 훅을 실행할 때 응답 상태를 자동으로 감지합니다. $exceptions->render() 콜백 안에서 에러 응답을 렌더링하는 경우, 에러 메타데이터가 적용되도록 렌더링 전에 Head::status(404)를 호출하세요.

Open Graph

og 메서드로 Open Graph 속성을 설정할 수 있습니다. 반복 가능한 미디어는 최상위 메서드를 사용해 named 인수로 직접 추가합니다:

use Laravel\Head\Enums\ImageType;
use Laravel\Head\Enums\OgType;

Head::og(type: OgType::Article, title: $post->title)
    ->ogImage($post->hero_image_url)
    ->ogImage(
        $post->gallery_image_url,
        alt: $post->gallery_image_alt,
        width: 1200,
        height: 630,
        type: ImageType::Jpeg,
    );

ogImage, ogVideo, ogAudio 메서드는 첫 번째 인수로 URL을 받으며, Open Graph 명세에서 지원하는 alt, width, height, type, secureUrl 등의 named 인수를 선택적으로 받습니다.

이미지 MIME 타입은 ImageType 열거형(ImageType::Svg, ImageType::Png, ImageType::Jpeg, ImageType::Webp)으로 전달할 수 있습니다.

NOTE

문서의 title과 description은 og:title과 og:description이 없을 때 자동으로 채워줍니다.

다른 속성 없이 단일 Open Graph 이미지만 필요하다면 og 메서드의 image named 인수를 사용하세요:

Head::og(
    type: OgType::Website,
    title: $page->title,
    description: $page->description,
    image: $page->og_image_url,
);

og(image: ...)와 ogImage(...)는 동일한 이미지 목록에 씁니다. 표현력에 따라 원하는 방식을 선택하세요. 제품이나 아티클 속성 같은 커스텀 Open Graph 확장에는 meta 메서드를 사용하세요.

X / Twitter 카드

Open Graph에서 사용한 타이틀, description, 이미지를 그대로 X / Twitter 카드에도 활용하려면 기본값에 twitter()를 등록하세요:

use Laravel\Head\Enums\TwitterCard;
use Laravel\Head\Facades\Head;
use Laravel\Head\HeadBuilder;

Head::defaults(fn (HeadBuilder $head) => $head->twitter(
    card: TwitterCard::SummaryWithLargeImage,
));

이후 페이지별 메타데이터를 설정합니다:

Head::title('Laravel Head 소개')
    ->description('Laravel 문서 head 메타데이터를 위한 유창한 API.')
    ->ogImage('https://example.com/social.jpg', alt: 'Laravel Head 소개');

이렇게 하면 대응하는 Twitter 태그가 자동으로 렌더링됩니다:

<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="Laravel Head 소개">
<meta name="twitter:description" content="Laravel 문서 head 메타데이터를 위한 유창한 API.">
<meta name="twitter:image" content="https://example.com/social.jpg">
<meta name="twitter:image:alt" content="Laravel Head 소개">

특정 페이지에서 Twitter 값을 직접 지정할 수도 있습니다:

Head::twitter(title: $post->social_title)
    ->twitterImage($post->social_image_url, alt: $post->title);

라우트 메타데이터에서는 twitter와 twitterImage를 사용하세요.

테마 색상

테마 색상은 전역, 라우트, 런타임 어디서든 설정할 수 있습니다:

Head::themeColor('#0f172a');

이는 <meta name="theme-color"> 태그를 렌더링합니다. 미디어 쿼리별 테마 색상이 필요하다면 Media 열거형을 사용하세요:

use Laravel\Head\Enums\Media;

Head::themeColor('#ffffff', media: Media::Light)
    ->themeColor('#111827', media: Media::Dark);

Media 열거형에는 Portrait와 Landscape도 포함됩니다. media 인수에 커스텀 미디어 쿼리 문자열을 직접 전달할 수도 있습니다.

라우트 메타데이터에서는 동일한 camelCase 키로 단일 테마 색상을 지정할 수 있습니다:

Route::view('/dashboard', 'dashboard')->withHead(
    themeColor: '#0f172a',
);

앱 메타데이터 및 아이콘

Laravel Head는 일반적인 브라우저 및 앱 메타데이터를 위한 메서드를 제공합니다:

use Laravel\Head\Enums\ImageType;
use Laravel\Head\Enums\Media;

Head::applicationName('Laravel')
    ->colorScheme('light dark')
    ->referrer('strict-origin-when-cross-origin')
    ->viewport('width=device-width, initial-scale=1')
    ->appleWebAppTitle('Laravel')
    ->webAppCapable()
    ->appleWebAppStatusBarStyle('black')
    ->favicon('/favicon.svg', type: ImageType::Svg)
    ->icon('/favicon-32x32.png', type: ImageType::Png, sizes: '32x32')
    ->appleTouchIcon('/apple-touch-icon.png', sizes: '180x180')
    ->appleTouchStartupImage('/launch.png', media: Media::Portrait)
    ->maskIcon('/safari-pinned-tab.svg', color: '#111827')
    ->manifest('/site.webmanifest');

favicon 메서드는 icon 메서드의 별칭으로, type, sizes, media 인수를 동일하게 받습니다.

라우트 메타데이터에서도 동일한 이름을 사용합니다:

use Laravel\Head\Enums\ImageType;
use Laravel\Head\Enums\Media;

Route::view('/dashboard', 'dashboard')->withHead(
    applicationName: 'Laravel',
    colorScheme: 'light dark',
    appleWebAppTitle: 'Laravel',
    webAppCapable: true,
    appleWebAppStatusBarStyle: 'black',
    favicon: [
        ['href' => '/favicon.svg', 'type' => ImageType::Svg],
        ['href' => '/favicon-32x32.png', 'type' => ImageType::Png, 'sizes' => '32x32'],
    ],
    appleTouchIcon: ['href' => '/apple-touch-icon.png', 'sizes' => '180x180'],
    appleTouchStartupImage: ['href' => '/launch.png', 'media' => Media::Portrait],
    manifest: '/site.webmanifest',
);

프로그레시브 웹 앱

pwa 메서드는 설치 가능한 웹 앱에 필요한 공통 <head> 태그를 한 번에 설정합니다:

Head::pwa(
    name: 'Laravel',
    manifest: '/site.webmanifest',
    themeColor: '#0f172a',
    appleTouchIcon: '/apple-touch-icon.png',
    appleWebAppStatusBarStyle: 'black',
);

이 메서드는 앱 이름, 웹 앱 매니페스트 링크, iOS 독립 실행형(standalone) 메타데이터를 렌더링합니다. 테마 색상, Apple 상태 표시줄 스타일, Apple 터치 아이콘이 제공된 경우 함께 렌더링됩니다. 웹 앱 매니페스트 생성과 서비스 워커 등록은 직접 처리해야 합니다.

pwa 메서드는 기본값 또는 런타임 메타데이터에서 사용할 수 있습니다. 라우트 메타데이터에서는 위에서 설명한 개별 속성을 사용하세요.

성능 및 검색 엔진 최적화

Laravel Head는 성능 힌트, 페이지네이션 링크, 로케일 대안(alternates), 피드 검색을 렌더링합니다:

Head::preload(asset('fonts/inter.woff2'), as: 'font', crossorigin: true)
    ->prefetch(asset('images/next.webp'))
    ->preconnect('https://cdn.example.com')
    ->dnsPrefetch('https://analytics.example.com')
    ->paginate($posts)
    ->alternates([
        'ko' => 'https://example.com/ko/about',
        'en' => 'https://example.com/en/about',
        'x-default' => 'https://example.com/about',
    ])
    ->feed('/feed', title: 'Laravel RSS')
    ->feed('/feed.atom', type: 'atom', title: 'Laravel Atom');

로컬 에셋의 경우 preloadAsset()과 prefetchAsset()을 사용하면 asset() 헬퍼로 URL을 자동 해석하고 파일 확장자에서 as 속성을 자동 감지합니다. 폰트 preload는 같은 출처(origin)의 폰트에도 스펙상 필수인 crossorigin을 자동으로 포함합니다:

Head::preloadAsset('fonts/inter.woff2')
    ->prefetchAsset('images/next.webp');

<link rel="preload" href="https://example.com/fonts/inter.woff2" as="font" crossorigin>
<link rel="prefetch" href="https://example.com/images/next.webp" as="image">

as를 명시적으로 전달하면 자동 감지를 재정의합니다. preloadAsset은 as 속성을 감지할 수 없으면 예외를 던집니다(브라우저가 as 없는 preload를 무시하기 때문). prefetchAsset은 감지 실패 시 해당 속성을 생략합니다.

커스텀 태그

전용 메서드가 없는 태그는 meta()와 link()를 사용하세요:

Head::meta('format-detection', 'telephone=no')
    ->meta('article:author', $post->author->name)
    ->link('search', '/opensearch.xml', [
        'type' => 'application/opensearchdescription+xml',
        'title' => 'Laravel 검색',
    ])
    ->link('me', 'https://social.example.com/@laravel');

브라우저가 특정 조건에서만 태그를 적용하도록 미디어 쿼리를 포함할 수 있습니다:

use Laravel\Head\Enums\Media;

Head::meta('theme-color', '#ffffff', media: Media::Light)
    ->meta('theme-color', '#111827', media: Media::Dark);

meta 메서드는 일반 메타 태그에는 name 속성을 사용합니다. Open Graph(og:)나 아티클 메타데이터(article:)처럼 property 속성을 주로 사용하는 키에는 자동으로 전환합니다:

Head::meta('description', 'Laravel 소개')
    ->meta('og:title', 'Laravel 소개');

<meta name="description" content="Laravel 소개">
<meta property="og:title" content="Laravel 소개">

property: true 또는 property: false를 전달해 속성을 명시적으로 선택할 수도 있습니다.

스키마

내장 스키마 빌더는 일반적인 JSON-LD 타입을 지원합니다:

use Laravel\Head\Enums\OfferAvailability;
use Laravel\Head\Facades\Schema;

Head::schema(
    Schema::product()
        ->name($product->name)
        ->offers(
            Schema::offer()
                ->price($product->price)
                ->currency('KRW')
                ->availability(OfferAvailability::InStock)
        )
);

내장 팩토리 메서드는 article, blogPosting, product, offer, brand, breadcrumbs, faq, organization, person, webPage, webSite입니다. 알 수 없는 팩토리 메서드는 제네릭 스키마 객체를 생성하므로 커스텀 schema.org 타입도 표현할 수 있습니다.

JSON-LD 스키마 데이터가 유효하지 않으면 Laravel Head는 비프로덕션 환경에서 예외를 던지고, 프로덕션 환경에서는 경고를 로그에 기록합니다.

브레드크럼

브레드크럼 항목은 하나씩 또는 한꺼번에 추가할 수 있습니다. 위치(position)는 추가 순서대로 자동 할당됩니다:

Head::schema(
    Schema::breadcrumbs()->items([
        '홈' => route('home'),
        '쇼핑' => route('shop.index'),
        '신발' => route('shop.category', 'shoes'),
    ])
);

item 메서드로 브레드크럼 항목을 하나씩 추가할 수도 있습니다:

Schema::breadcrumbs()
    ->item('홈', route('home'))
    ->item('쇼핑', route('shop.index'));

FAQ

FAQ 항목도 동일한 방식으로 추가합니다. question 메서드로 하나씩, questions 메서드로 한꺼번에 추가할 수 있습니다:

Head::schema(
    Schema::faq()->questions([
        'Laravel Head란 무엇인가요?' => '문서 head를 관리하기 위한 유창한 API입니다.',
        '무료인가요?' => '네, 오픈 소스입니다.',
    ])
);

커스텀 스키마

커스텀 스키마 타입을 명시적으로 등록할 수 있습니다:

use DateTimeInterface;
use Laravel\Head\Facades\Schema;
use Laravel\Head\Schema\SchemaObject;
use Laravel\Head\SchemaType;

#[SchemaType('JobPosting')]
class JobPosting extends SchemaObject
{
    public function title(string $title): static
    {
        return $this->set('title', $title);
    }

    public function datePosted(DateTimeInterface|string $date): static
    {
        return $this->date('datePosted', $date);
    }
}

Schema::register(JobPosting::class);

Head::schema(
    Schema::jobPosting()
        ->title('시니어 Laravel 개발자')
        ->datePosted(now())
);

렌더링

Laravel Head는 현재 응답에 맞는 메타데이터를 태그로 해석합니다. 렌더링 방식은 사용하는 스택에 따라 다릅니다.

HTML 렌더러는 @head 디렉티브와 Inertia에 head prop으로 공유되는 렌더링된 요소를 담당합니다. 배열 렌더러는 구조화된 데이터로 메타데이터가 필요한 애플리케이션을 위한 Head::toArray()를 처리합니다.

Blade

레이아웃의 <head> 안에 @head 디렉티브를 사용해 태그를 렌더링합니다:

<head>
    <meta charset="utf-8">
    @head
</head>

@head 디렉티브는 동기적으로 렌더링됩니다. 따라서 페이지 메타데이터는 레이아웃이 렌더링되기 전에 정의해야 합니다.

Livewire

Livewire 애플리케이션도 문서 레이아웃에서 동일한 @head 디렉티브를 사용합니다:

<head>
    @head
</head>

<body>
    {{ $slot }}

    @livewireScripts
</body>

별도의 Livewire 전용 설정은 필요하지 않습니다. Laravel Head 메타데이터는 요청 단위로 해석되고 리졸버도 요청 범위(request-scoped)입니다. 따라서 wire:navigate 방문마다 새로운 문서를 가져오며 @head 출력은 목적지 라우트의 메타데이터를 반영합니다. wire:navigate로 방문한 페이지는 컴포넌트 수준의 head 코드 없이도 적절한 라우트·런타임·에러 메타데이터를 받습니다.

Inertia

Inertia 루트 템플릿에서도 Inertia 고유 컴포넌트와 함께 @head 디렉티브를 사용합니다:

<html>
<head>
    <meta charset="utf-8">
    @head

    @viteReactRefresh
    @vite(['resources/css/app.css', 'resources/js/app.tsx'])
    <x-inertia::head />
</head>
<body>
    <x-inertia::app />
</body>
</html>

Inertia가 설치되어 있으면 Laravel Head는 페이지 관리 head를 렌더링된 요소 문자열 배열로 자동 직렬화하여 모든 페이지 객체의 head prop으로 공유합니다:

{
    "props": {
        "head": [
            "<title data-inertia=\"title\">대시보드 - Laravel</title>",
            "<meta data-inertia=\"description\" name=\"description\" content=\"애플리케이션 개요입니다.\">"
        ]
    }
}

createInertiaApp()을 호출하는 곳에서 Inertia의 serverHead 옵션을 활성화하세요. 이 옵션은 Inertia 3.5 이상에서 사용할 수 있습니다:

createInertiaApp({
    // ...
    serverHead: true,
});

각 페이지 관리 요소는 안정적인 data-inertia 키를 가집니다. @head 디렉티브가 초기 문서를 렌더링한 후 Inertia가 해당 요소를 인계받아 일반 방문, 즉시 방문(instant visits), 앞으로/뒤로 탐색 시 동기화 상태를 유지합니다. 요소는 최초 HTML 응답에 포함되므로 크롤러와 소셜 미리보기 봇도 JavaScript 없이 읽을 수 있습니다. 클라이언트 사이드 <Head> 컴포넌트는 필요하지 않습니다.

이 방식은 서버 사이드 렌더링(SSR) 유무와 관계없이 동작합니다. SSR 전용 진입점이 있다면 거기서도 serverHead를 활성화하세요. Laravel Head는 순서에 무관하게 @head와 <x-inertia::head /> 사이에서 페이지 관리 요소의 중복을 자동으로 제거하면서 JavaScript SSR이 생성한 다른 head 요소는 그대로 유지합니다.

NOTE

기존 Inertia 애플리케이션에 Laravel Head를 추가할 때는 resources/js/app.tsx와 resources/js/ssr.tsx의 타이틀 콜백을 제거하여 Laravel Head가 최종 문서 타이틀을 관리하도록 하세요. Inertia의 <Head> 컴포넌트로 관리하던 태그도 Laravel Head로 이전하여 두 시스템이 동일한 요소를 중복 정의하지 않도록 하세요.

head prop은 부분 리로드(partial reload) 응답에서는 생략되므로 Inertia는 마지막 전체 페이지의 head를 유지합니다. 즉시 방문도 백그라운드 응답이 도착할 때까지 현재 head를 유지합니다. 애플리케이션에서 이미 head prop을 사용하고 있다면 서비스 프로바이더에서 이름을 변경할 수 있습니다:

use Laravel\Head\Facades\Head;

public function boot(): void
{
    Head::inertia(prop: '_head');
}

그런 다음 serverHead: '_head'로 Inertia가 동일한 prop을 가리키도록 설정하세요.

정적 Inertia 태그

대부분의 태그는 Laravel Head가 페이지별로 적절한 값을 해석할 수 있도록 기본값, 라우트 메타데이터, 런타임 메타데이터에 배치해야 합니다. Inertia 글로벌은 첫 번째 HTML 응답에서 렌더링된 후 세션 내내 변경되지 않는 문서 태그에만 사용하세요.

서비스 프로바이더에서 Head::inertiaGlobals()로 등록합니다:

use Laravel\Head\Facades\Head;
use Laravel\Head\HeadBuilder;

Head::inertiaGlobals(function (HeadBuilder $head) {
    $head
        ->viewport('width=device-width, initial-scale=1')
        ->colorScheme('light dark')
        ->icon('/favicon.svg', type: 'image/svg+xml')
        ->appleTouchIcon('/apple-touch-icon.png', sizes: '180x180')
        ->manifest('/site.webmanifest');
});

Inertia 글로벌은 head prop에서 제외되고, data-inertia 소유권 속성 없이 렌더링되며, 첫 번째 응답 이후에는 절대 업데이트되지 않습니다. 뷰포트, 색상 스킴, 파비콘, 터치 아이콘, 매니페스트처럼 안정적인 브라우저 힌트에 적합합니다. 페이지별로 달라지거나 SEO와 관련되거나 나중에 재정의될 수 있는 태그는 defaults, 라우트 메타데이터, 런타임 메타데이터에 넣으세요.

렌더링된 태그 대신 구조화된 데이터로 해석된 메타데이터가 필요한 애플리케이션은 Head::toArray()를 호출할 수 있습니다. 반환된 데이터에는 타이틀, Open Graph 값, JSON-LD 스키마 등 해석된 메타데이터가 포함됩니다.