Is it ever a good idea to add children to next/document's Head? #13408

TyMick · 2020-05-26T17:53:49Z

TyMick
May 26, 2020

I was trying to fix a multiple viewport meta tags issue caused by adding a <meta> tag as a child of the Head component in _document.js, and I was thinking about adding some deduplicating functionality to _document.tsx that's similar to what already exists in next/head. But then I realized that if I did that, user-entered <head> elements in _document.js would override matching user-entered <head> elements from _app.js or individual pages.

I can't think of any <head> elements one would add to _document.js that can't be added to _app.js with next/head. I can see why _document.js needs its own <Head /> for rendering purposes, but should we discourage adding any children to this Head like we're currently discouraging adding <title> tags to _document.js?

next.js/packages/next/pages/_document.tsx

Lines 302 to 306 in 2828b01

    
           if (child?.type === 'title' && !isReactHelmet) { 
        
             console.warn( 
        
               "Warning: <title> should not be used in _document.js's <Head>. https://err.sh/next.js/no-document-title" 
        
             ) 
        
           }

Answered by lfades

May 26, 2020

next/head is dynamic, you can use it multiple times, update it, remove it, and your head tag will reflect those changes.

_document.js is only rendered once, in the server, and for your entire page, this is the one that generates the initial html tag that will be used for your page and it's not a place to save any tags that rely on dynamic data, or that only apply for some pages. A good use case for this one is for example to add a custom favicon link, or google analytics, something that you know only needs to be added once and has to be always there.

_app.js is similar in the way that it's also applied globally, but it does get rendered again every time you switch the current page, so it'…

View full answer

lfades · 2020-05-26T20:06:47Z

lfades
May 26, 2020
Collaborator

next/head is dynamic, you can use it multiple times, update it, remove it, and your head tag will reflect those changes.

_document.js is only rendered once, in the server, and for your entire page, this is the one that generates the initial html tag that will be used for your page and it's not a place to save any tags that rely on dynamic data, or that only apply for some pages. A good use case for this one is for example to add a custom favicon link, or google analytics, something that you know only needs to be added once and has to be always there.

_app.js is similar in the way that it's also applied globally, but it does get rendered again every time you switch the current page, so it's also dynamic (which is never the case for _document.js)

11 replies

willemmulder Dec 1, 2020

@timneutkens Hi Tim, what I do not understand is why the viewport meta should be handled by next/head and not in _document, especially because the viewport meta is a thing that many people want to set just once (i.e. sitewide). Then it would be more efficient to put it in _document, right?

TyMick Dec 1, 2020
Author

@willemmulder You're right, that does seem to violate the breakdown @lfades gave at the beginning of this thread. 🤔 The only reason I can see right now for the current behavior is because document/head doesn't currently have any deduplicating functionality like next/head, so it isn't able to override the default viewport meta tag.

If document/head were given the ability to override just the default viewport, that would solve one instance of multiple viewport tags (#13230) but allow for other instances of multiple viewport tags whenever a developer adds one to document/head and to next/head somewhere else. So a warning is probably necessary somewhere, but come to think of it, maybe the latter situation the better one to warn about.

It would take some extra work, but if we let document/head override just the default viewport, and then adjusted next/head so that it can override the default but can't override a viewport added to document/head, then Next.js could just warn people when they define multiple viewport tags themselves (in both document/head and next/head) instead of just warning them when they define a single viewport tag in a difficult place (document/head). A developer adding two of their own viewport tags does seem like the bigger blunder to me.

Now I'm intrigued. I'll open up a new issue (#19720) to see if anyone else thinks this is a good idea. 👍🏼

willemmulder Dec 1, 2020

@tywmick Totally agree! I don't have a very deep understanding of the current process (and its design and implications) but would it even be possible to allow people to override a viewport tag in next/head...? I.e.

document/head uses a) the defined viewport or b) else the default (if nothing is defined)
The result is passed to next/head which in turn will a) use the defined viewport if there is one or b) else will use the result from document/head (which will always be defined, right?)

Would that harm anything?

TyMick Dec 1, 2020
Author

@willemmulder Yeah, so currently, the default head lives in next/head, and it only includes two tags (or one if you're in AMP mode):

next.js/packages/next/next-server/lib/head.tsx

Lines 11 to 17 in c8cd77a

    
           export function defaultHead(inAmpMode = false): JSX.Element[] { 
        
             const head = [<meta charSet="utf-8" />] 
        
             if (!inAmpMode) { 
        
               head.push(<meta name="viewport" content="width=device-width" />) 
        
             } 
        
             return head 
        
           }

Farther down in that file it merges that default head with every other next/head child defined for a given page, filtering out any internal conflicts, and the result of that function is what gets injected into the HTML head. I feel like there's got to be a way, though, to tell next/head what's already been added to document/head, so next/head can remove anything that conflicts with it, including the defaults. Then, only if the conflict was something manually added to next/head by the user is there a need to warn them.

So the process would then be

document/head adds any viewport tag that's defined within it to the initial HTML, without concerning itself about defaults or anything. No warnings necessary.
The list of elements that document/head added gets passed to next/head's filter somehow.
next/head filters out all elements that conflict with document/head children.
- If a conflict filtered out was part of defaultHead, that's perfect.
- If a conflict filtered out was a manually defined next/head child, then generate a warning, because the user goofed by defining conflicting tags in multiple places themselves.
next/head injects the results into the page.

willemmulder Dec 3, 2020

Yes exactly!

willemmulder · 2021-10-27T12:40:20Z

willemmulder
Oct 27, 2021

Just for those that missed the link: issue #19720 contains the proposal for a more permissive use of document/head!

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Is it ever a good idea to add children to next/document's Head? #13408

{{title}}

{{editor}}'s edit

{{editor}}'s edit

Replies: 2 comments 11 replies

{{title}}

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{title}}

Select a reply

Is it ever a good idea to add children to next/document's Head? #13408

TyMick May 26, 2020

Replies: 2 comments · 11 replies

lfades May 26, 2020 Collaborator

willemmulder Dec 1, 2020

TyMick Dec 1, 2020 Author

willemmulder Dec 1, 2020

TyMick Dec 1, 2020 Author

willemmulder Dec 3, 2020

willemmulder Oct 27, 2021

TyMick
May 26, 2020

Replies: 2 comments 11 replies

lfades
May 26, 2020
Collaborator

TyMick Dec 1, 2020
Author

TyMick Dec 1, 2020
Author

willemmulder
Oct 27, 2021