RFC: `next/third-parties` #48256

housseindjirdeh · 2023-04-11T16:39:32Z

housseindjirdeh
Apr 11, 2023
Collaborator

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 · 2023-04-11T18:35:28Z

thedaviddias
Apr 11, 2023

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 😉

1 reply

housseindjirdeh Apr 12, 2023
Collaborator Author

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 · 2023-04-11T19:08:04Z

JonatanSalas
Apr 11, 2023

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.

1 reply

housseindjirdeh Apr 12, 2023
Collaborator Author

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 · 2023-04-11T19:12:48Z

sandeep1995
Apr 11, 2023

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.

0 replies

emrecoban · 2023-04-11T19:15:46Z

emrecoban
Apr 11, 2023

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.

2 replies

housseindjirdeh Apr 12, 2023
Collaborator Author

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 Apr 13, 2023

Thank you for your explanation.

JamesSingleton · 2023-04-11T23:07:17Z

JamesSingleton
Apr 11, 2023

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

0 replies

prateekbh · 2023-04-12T07:04:24Z

prateekbh
Apr 12, 2023

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?

1 reply

housseindjirdeh Apr 12, 2023
Collaborator Author

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 · 2023-04-12T11:05:58Z

icyJoseph
Apr 12, 2023

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!

5 replies

Tagvi Apr 12, 2023

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 Apr 12, 2023

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 Apr 12, 2023
Collaborator Author

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 Apr 13, 2023

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 Apr 13, 2023

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 · 2023-04-12T18:21:23Z

marko-hologram
Apr 12, 2023

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 😄

1 reply

housseindjirdeh Apr 12, 2023
Collaborator Author

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 · 2023-07-13T06:00:51Z

Multiply
Jul 13, 2023

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.

1 reply

housseindjirdeh Aug 8, 2023
Collaborator Author

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 · 2023-08-08T15:38:18Z

housseindjirdeh
Aug 8, 2023
Collaborator Author

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!

0 replies

housseindjirdeh · 2023-08-10T18:29:41Z

housseindjirdeh
Aug 10, 2023
Collaborator Author

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!

2 replies

joey-ma Oct 27, 2023

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 Oct 27, 2023
Collaborator Author

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 · 2023-08-20T06:20:38Z

laugharn
Aug 20, 2023

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

3 replies

mryechkin Oct 10, 2023

Same here. Would love to know this as well

sandrinjoy Oct 17, 2023

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 Oct 27, 2023
Collaborator Author

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 · 2023-10-27T15:18:00Z

akush
Oct 27, 2023

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.

0 replies

housseindjirdeh · 2023-10-27T18:16:31Z

housseindjirdeh
Oct 27, 2023
Collaborator Author

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.

0 replies

giannif · 2023-10-31T20:23:46Z

giannif
Oct 31, 2023

@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

1 reply

YasielCabrera Nov 3, 2023

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 · 2023-11-04T09:38:42Z

sillyas2010
Nov 4, 2023

✅ 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

0 replies

webahua · 2023-11-28T05:51:23Z

webahua
Nov 28, 2023

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.

1 reply

webahua Nov 28, 2023

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 · 2023-11-29T06:54:01Z

yannxaver
Nov 29, 2023

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?

0 replies

yannxaver · 2023-11-29T06:58:03Z

yannxaver
Nov 29, 2023

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?

1 reply

SivaGanesh56 Jul 19, 2024

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

yamatsum · 2024-11-07T12:49:16Z

yamatsum
Nov 7, 2024

@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?

0 replies

jhssilva · 2024-11-17T18:16:26Z

jhssilva
Nov 17, 2024

The GoogleMapsEmbed unfortunately doesn't have the title option which then throws the following accessibility warning:
<frame> or <iframe> elements do not have a title
API described here: https://nextjs.org/docs/app/building-your-application/optimizing/third-party-libraries#google-maps-embed

0 replies

RFC: next/third-parties #48256

housseindjirdeh Apr 11, 2023 Collaborator

Goal

Background

Proposal

Maintenance

Demo

Selection of Third Parties

Replies: 21 comments · 20 replies

housseindjirdeh Apr 12, 2023 Collaborator Author

housseindjirdeh Apr 12, 2023 Collaborator Author

housseindjirdeh Apr 12, 2023 Collaborator Author

housseindjirdeh Apr 12, 2023 Collaborator Author

housseindjirdeh Apr 12, 2023 Collaborator Author

housseindjirdeh Apr 12, 2023 Collaborator Author

housseindjirdeh Aug 8, 2023 Collaborator Author

housseindjirdeh Aug 8, 2023 Collaborator Author

housseindjirdeh Aug 10, 2023 Collaborator Author

housseindjirdeh Oct 27, 2023 Collaborator Author

housseindjirdeh Oct 27, 2023 Collaborator Author

housseindjirdeh Oct 27, 2023 Collaborator Author

RFC: `next/third-parties` #48256

housseindjirdeh
Apr 11, 2023
Collaborator

Replies: 21 comments 20 replies

housseindjirdeh Apr 12, 2023
Collaborator Author

housseindjirdeh Apr 12, 2023
Collaborator Author

housseindjirdeh Apr 12, 2023
Collaborator Author

housseindjirdeh Apr 12, 2023
Collaborator Author

housseindjirdeh Apr 12, 2023
Collaborator Author

housseindjirdeh Apr 12, 2023
Collaborator Author

housseindjirdeh Aug 8, 2023
Collaborator Author

housseindjirdeh
Aug 8, 2023
Collaborator Author

housseindjirdeh
Aug 10, 2023
Collaborator Author

housseindjirdeh Oct 27, 2023
Collaborator Author

housseindjirdeh Oct 27, 2023
Collaborator Author

housseindjirdeh
Oct 27, 2023
Collaborator Author