RFC: next/third-parties

[housseindjirdeh]

Goal

Improve the user and developer experience of loading popular third-party libraries in a Next.js application.

Background

95% of Next.js websites load at least one third-party resource. The next/script component currently provides developers with an API that allows them to control when third-party scripts load, but we can make this process simpler for many popular third-party resources by providing pre-configured wrapper components.

By providing Next.js developers with a focused set of components, we can:

• Simplify the developer experience of loading popular third-party resources
• Ensure that popular third-party resources are loaded efficiently and continue to do so as best practices evolve (e.g. wrapped inside a Client Component)
• Provide more third-party specific warnings and errors (e.g. if a critical property or attribute is missing for a particular third-party script, an ESLint warning or error can be surfaced)

Proposal

We can provide Next.js developers with a next/third-parties package that wraps many popular third-party libraries, improving the developer and user experience of loading and using these libraries.

import { GoogleAnalytics } from 'next/third-parties'

export default function Page() {
  return (
    <>
      <GoogleAnalytics />
    </>
  );
}

To not increase the install/package size of Next.js, and because it will involve configurations for third-party code — this package can live separate from the core next library but remain within the same monorepo.

Maintenance

One of the issues of managing third-party code in a centralized module is dealing with the maintenance burden. Maintainers of next/third-parties will have to continuously monitor and update underlying loading techniques as the third-parties themselves change and adapt to newer web practices.

To solve this, and to prevent duplicating identical loading recommendations for the same third-parties in different places, the Chrome Aurora team is working on Third Party Capital, an NPM library that consolidates best practices for popular third-parties in a single place. For Next.js, we have the option of either relying on this library or creating entirely custom components (or using either of the two approaches depending on the resource itself).

Demo

Here’s a link to a working next/third-parties prototype that demonstrates how Third Party Capital could be used under the hood.

To summarize how this demo works:

• All the information required to load a number of third-parties in a performant way are stored as JSON in the third-party-capital repo
• A prototype of a next/third-parties library is created inside of the Next.js monorepo that is responsible for creating Next.js-specific wrapper components. It utilizes a base-level component that injects any required stylesheets, scripts, and 3P page content after the main content of the page has rendered.
• A node script takes all of the exports in the third-party-capital repo and automatically generates Next.js components for each third-party at build time. Now everytime next/third-parties is version bumped along with its third-party-capital dependency, all third-party components are automatically updated and/or generated with zero maintenance required from the framework side.

This prototype is only a rough demonstration of how Third Party Capital can be used to minimize the amount of maintenance required of framework authors and maintainers. This implementation is subject to change.

Selection of Third Parties

For the initial rollout of next/third-parties, we suggest supporting a small number of popular third-parties whose performance can be improved by using an alternative method of loading than the general recommended practice. Some examples that have already been included in Third Party Capital:

Google Analytics

64% of Next.js sites use Google Analytics. The latest version, which must be used from July 1, 2023 onwards, requires users to fetch an 80 kB gtag.js script. A <GoogleAnalytics /> component could offload this to a web worker via Partytown or, at the very least, simplify the current developer experience.

YouTube Embed

YouTube resources are one of the most popular render-blocking third-parties on the web today. A <YoutubeEmbed /> component could leverage the techniques used in lite-youtube-embed to load embedded videos significantly faster.

Google Maps

8.5% of Next.js sites use Google Maps which is also one of the most popular render-blocking third-parties on the web. A <GoogleMapsEmbed /> component could automatically include the loading=”lazy” property to ensure that it is only loaded when it is close to the device viewport.

These are only some examples of third-parties that we think developers can benefit from using a framework wrapper but many others will also be considered (for example: Sentry, DataDog, Facebook Pixel).

If you have any suggestions for third-parties you’d like to see included, please leave a comment below!

[thedaviddias]

Thanks for proposing improvements to better handle third-party scripts in NextJS. I think this is definitely a topic that needs better care.

On the advertisement side, we can think of

• Google Publisher Tag (https://securepubads.g.doubleclick.net/tag/js/gpt.js)
• AdSense (https://www.google.com/adsense/search/ads.js, https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js etc...)
• Amazon TAM (https://c.amazon-adsystem.com/aax2/apstag.js)

I would have suggested PrebidJS and Adobe Audience Manager script, but usually those are installed locally.

Also maybe next/third-parties could actually be divide into categories... Some scripts are usually for monitoring and analytics, others may be more advertising related etc...

I know it's just the beginning, hope to follow where this will land 😉

[housseindjirdeh]

Thanks for all the great suggestions David :)

Also maybe next/third-parties could actually be divide into categories... Some scripts are usually for monitoring and analytics, others may be more advertising related etc...

I'll think about this some more! I wonder if having nested exports would help here (e.g. next/third-parties/analytics, etc.) or if that would be too much 🤔

[JonatanSalas]

Hey! At BlackBox Vision OSS we're developed 2 packages:

• Google Analytics for Next.js
• Google Double Click for Publishers (WIP)

If this RFC moves, we'd love to contribute by giving the code from our packages directly if possible! And to provide engineers to keep contributing on.

[housseindjirdeh]

That's really kind of you, thank you! I'll definitely keep you in the loop if we need any assistance. It's great to see some examples of similar packages in the wild :)

[sandeep1995]

It is important to keep in mind that the maintenance burden can be significant, and relying on a centralized module for third-party code can create dependencies and potential issues.

Overall, this proposal seems like a step in the right direction for managing third-party scripts in Next.js.

[emrecoban]

I'm not sure if we need this package since we already have next/script. Personally, I prefer not to use two packages that serve the same purpose. Your package currently supports three scripts, and although I believe you will add more in the future, there may be a specific script that I want to use in my project which is not included in your package.

Thank you for your contribution.

[housseindjirdeh]

This is great feedback, thank you.

I'm not sure if we need this package since we already have next/script.

This effort isn't meant to replace next/script, but to provide some helpers for common use cases.
I initially thought that about providing these new exports directly in the same next/script package, but not every third-party resource is necessarily a script resource (e.g. Google Maps Embed). We also thought it might make more sense to not increase the install size of next and keep all third-party content in a separate library.

Personally, I prefer not to use two packages that serve the same purpose.

One piece of feedback we've heard often is that although next/script is available, it can still be a bit confusing figuring out how to load some popular third-parties. Take Google Analytics/GTM as an example:

// ...
  <Head>
    <Script
      id="gtag"
      dangerouslySetInnerHTML={{
        __html: `
              window.dataLayer = window.dataLayer || [];
              function gtag(){dataLayer.push(arguments);}
              gtag('js', new Date());

              gtag('config', '${gtag.GA_TRACKING_ID}', {
                page_path: window.location.pathname,
              });
            `,
      }}
    />
  </Head>
  <Script
    strategy="afterInteractive"
    src={`https://www.googletagmanager.com/gtag/js?id=${gtag.GA_TRACKING_ID}`}
  />
// ...

For such a common use case (over 60% of Next.js sites fetch Google Analytics) - we think it could be super helpful to just provide a component that does all the heavy lifting for them. We can also vet certain techniques (e.g. off-loading to a web worker) and provide that for users automatically.

import { GoogleAnalytics } from 'next/third-parties'

export default function Page() {
  return (
    <>
      <GoogleAnalytics id="..."/>
    </>
  );
}

Your package currently supports three scripts, and although I believe you will add more in the future, there may be a specific script that I want to use in my project which is not included in your package.

Yeah there's no way we can support every third-party resource out there, but we're hoping to support a number of the most popular ones used today. For the remaining, next/script will always be available to use. :)

[emrecoban]

Thank you for your explanation.

[JamesSingleton]

I would love to see AdSense added, maybe Plausible (but I know that would conflict with Vercel's acquisition of Splitbee)

[prateekbh]

This looks great @housseindjirdeh ! Just curious does it continue to use Next Script element under the hood?
are we able to reuse the prior work or are there difference in the implementation?
If not, is there a good way of consolidating these efforts?

[housseindjirdeh]

Thanks @prateekbh! And you got that right, this will in all likelihood use next/script under the hood. This isn't an effort to replace next/script but rather provide some useful helpers on top for common use cases.

[icyJoseph]

Throwing in my two cents. Would it make sense to bake this into the next config object?

// Mock - non existing API
const config = {
  poweredByHeader: false,
  reactStrictMode: true,
  analytics: {
    googleAnalytics: true, // or a function which receives the default config, runtime and NODE_ENV?
    // or process.env.NEXT_PUBLIC_GA_KEY
  },
  monitoring: {
    someMonitoringAPI: true,
  },
};

• It would remove it from the Developer driven React tree, similarly to how Strict Mode, Routing Providers, etc, are managed
  • Then it becomes Next.js' responsibility to attach them to the React tree
• It could potentially expose fine grained configuration for scripts, similarly to Webpack's key in NextConfig
  • Using a React component limits the config to props, or callbacks
    • A component factory pattern could be used as well
• No need to think about passing stable references to the components
  • Analytics tools rarely change at runtime
• If for some reason a callback is needed to interact with the script it can be imported from next/third-party, which would/should have a stable reference

import { pageview } from 'next/third-party/ga';

// report a page view outside React's tree
pageview('/foo');

Love this initiative, I was a bit taken aback by the GA changes taking place in July, so I moved to the https://github.com/vercel/analytics, and it was a really great DX improvement!

[Tagvi]

Having them as components may come in handy in very niche cases where mounting a certain component could opt the user in analytics. You can have something like disabledRoutes in the config but it still won't be as flexible.
Edit: On second thought, what if the application using such components from the module decides to use the analytics but then has to disable it, say for another route, since Next.JS becomes an SPA on load, further reroutes will keep the script running even if it gets unmounted. one option could be forcing the page to refresh, or to provide some hooks (not necessarily react) and/or an option where the component can just accept strings for routes it should disable itself on.

[icyJoseph]

Right, perhaps the component approach would integrate better with consent management tools.

On paper anything is possible, but it feels like for this use case my suggestion would fall short, or rather, would require some complicated API signatures in the next config object, just to accommodate them.

Given that in the EU, consent management is very important, perhaps it is enough of a reason to not consider this approach, or?

[housseindjirdeh]

Cheers thanks for the feedback @icyJoseph and @Tagvi.

Would it make sense to bake this into the next config object?

Great point, and all your reasoning makes total sense. I also had the idea of baking certain APIs into the config object that don't necessarily need a component (e.g. Google Analytics like you mentioned) and provide others via wrapper components (e.g. content embeds). My worry there was that by providing these utilities in multiple places, it could be confusing for developers. Do you think using both approaches makes sense?

Aside from that, I agree that solely sticking to the next config object could be a bit tricky in the long run - especially if we want to provide support for including certain third-parties on a page-level rather than the entire app.

[icyJoseph]

My worry there was that by providing these utilities in multiple places, it could be confusing for developers. Do you think using both approaches makes sense?

You are correct there. I think the next/image is a good example of just the right balance, but it doesn't seem to translate into next/third-parties, which is more akin to next/script.

For this use case, all things considered, maybe the next config option would just translate into more complexity, which is what this RFC wants to reduce.

[marko-hologram]

I would personally vote for the component approach. Seems to be most flexible, but still really easy to use at the end of the day.

My worry there was that by providing these utilities in multiple places, it could be confusing for developers

Totally agree. Currently there is already conflicting information on how to integrate some of these (do you use _app or _document for example) so putting these in multiple places would again cause confusion in my opinion. It would also probably be a bit of a maintenance burden for Next.js maintainers as well.

[marko-hologram]

I do support this idea. There were few instances where I found conflicting information on how to load some of these third party scripts so having an official way these are loaded in the most performant way is great.

Google Analytics

64% of Next.js sites use Google Analytics. The latest version, which must be used from July 1, 2023 onwards, requires users to fetch an 80 kB gtag.js script. A <GoogleAnalytics /> component could offload this to a web worker via Partytown or, at the very least, simplify the current developer experience.

Google Maps

8.5% of Next.js sites use Google Maps which is also one of the most popular render-blocking third-parties on the web. A <GoogleMapsEmbed /> component could automatically include the loading=”lazy” property to ensure that it is only loaded when it is close to the device viewport.

Btw, just noticed that these percentage links that go to BigQuery are actually for Nuxt.js, not Next.js. That probably needs to be updated 😄

[housseindjirdeh]

I'm glad you like the idea! We're hopeful that this can reduce the confusion that many developers similarly face when trying to include certain third-parties.

Btw, just noticed that these percentage links that go to BigQuery are actually for Nuxt.js, not Next.js. That probably needs to be updated 😄

Lol, oops. At least I pasted the correct numbers 😅.

Just fixed it, thank you!

[Multiply]

Would supporting user consent to conditionally load libraries make sense for this RFC?

Currently, we use GTM to load most of our libraries when the consent events are sent, but hooking it up in the code would most likely be more performant, and allow for loading certain libraries sooner.

It should be pretty trivial to conditionally load the libraries on the client with this spec, but having a wrapper around X consent management API events would be a nice addition.

[housseindjirdeh]

This is interesting and something we haven't yet considered. Not sure if it would be best to include consent management as part of this RFC for simplicity reasons though 🤔

Just to make sure I fully understand though, are you thinking of a brand new API within the next/third-parties package that allows for conditional loading of 3Ps based on user consent? What would you like an API like this to look like?

[housseindjirdeh]

For folks following this thread, the @next/third-parties package has been merged 🚀 . It includes two third-parties at the moment (YoutubeEmbed and GoogleMapsEmbed) and we'll be rolling out more in the coming weeks/months.

See the README for some early instructions on how to use it. This package is still early and experimental so please be careful when using in production. However, we would value any feedback if you give it a shot!

[housseindjirdeh]

The next two libraries we're currently working on are Google Tag Manager and gtag. We've put some thought into it and realized that providing a component for tag managers and libraries that don't render any content (e.g. Google Analytics) might not be the best approach.

I wrote a follow up RFC for this: #53868. Please feel free to drop some feedback!

[joey-ma]

Understanding that this is a work in progress, I'm getting Cannot find module '@next/third-parties/google' or its corresponding type declarations.ts(2307). I can do @ts-ignore for this error, but am wondering if it is still worthwhile to try out the current Google Tag Manager documentation?

[housseindjirdeh]

Ah we'll get that fixed! Yes you should still absolutely be able to try out and use the current implementation.

Will let you know as soon we get the TS issue fixed 🙏

[laugharn]

Is this package being published? When I attempt to install it I get a @next/third-parties is not in the npm registry error.

[mryechkin]

Same here. Would love to know this as well

[sandrinjoy]

it is currently in the next canary releases.
next version - 13.5.6-canary.3 , use it with caution, since several other changes might also be there present in these releases

[housseindjirdeh]

Yes we made the library public as of last week if I recall correctly. You can use it now but it is still experimental so you should still proceed with some caution. However, we're going to try our very best not to introduce any breaking changes whatsoever.

[akush]

Is there a proposal to include firebase? If not, can we add that? Since many of us has web n app, we are using firebase analytics to do event tracking in both. Also, other firebase features like remote-config and etc can be used as well.

[housseindjirdeh]

If anyone is trying to install the library but is seeing a peerDep error, #57515 fixes it. In the meantime, you can either use the latest next canary or install the package with --legacy-peer-deps.

[giannif]

@housseindjirdeh I think the package.json is missing a types field. I don't get types in my project. I see types fields in other next packages like here and I use types fields in my libraries. If I use // @ts-ignore the imports still work

[YasielCabrera]

I have the same situation, the package works but the types are missing.

Version:

"@next/third-parties": "^14.0.1",
"next": "13.5.1",

[sillyas2010]

✅ Cannot find module '@next/third-parties/google' or its corresponding type declarations.ts(2307)

@giannif, @YasielCabrera, @joey-ma and others, if you want to have temporary fix for missing types - then create next-third-parties.d.ts somewhere in your project, make it to have such content (I used only GTM, so feel free to export other attributes you need):

export { GoogleTagManager, sendGTMEvent } from '@next/third-parties/dist/google'

Also add such content to your tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@next/third-parties/google": ["./types/next-third-parties.d.ts"],
    }
  },
}

Where ./types/next-third-parties.d.ts is your parth to next-third-parties.d.ts

[webahua]

I have a problem now. I need to resubmit the Google tracking code GTM for every page, but my current GTM code will only be submitted the first time that the page is re-rendered. The jump within the page uses the Link tag, which causes the page to be preloaded, the page will not be re-rendered, and GTM will not be triggered again.

[webahua]

I am currently using window.location.xx to prompt the page DOM to re-render, but I think this is not a good solution. Or creating document.createElement('script') in useEffect to insert GTM is not feasible. This method of tracking is not perfect.

[yannxaver]

The Google maps embed example on the website passes 100% as width. (https://nextjs.org/docs/app/building-your-application/optimizing/third-party-libraries#options-1).

This doesn't work in reality because width is typed as number.

export type GoogleMapsEmbed = {
    height?: number;
    width?: number;
    mode: 'place' | 'view' | 'directions' | 'streetview' | 'search';
    apiKey: string;
    style: string;
    allowfullscreen: boolean;
    loading: 'eager' | 'lazy';
    q?: string;
    center?: string;
    zoom?: string;
    maptype?: string;
    language?: string;
    region?: string;
};

Even if I ignore the typing and pass '100%', the map is still not displayed with 100% width. styling={'width: 100%;'} also does not work. How can I achieve 100% width?

[yannxaver]

I have replaced a simple iframe with the Google maps embed component and the amount and timing of JavaScript loaded is exactly the same. The lighthouse scores are also identical. What is the benefit of using the Google maps embed component?

[SivaGanesh56]

it looks like there is no support for web worker / party town in nextJs app router

[yamatsum]

@next/third-parties is currently an experimental library under active development. We recommend installing it with the latest or canary flags while we work on adding more third-party integrations.

When is it scheduled to become stable? Can the already added GTM etc. be used stably?