From 9ca0c142b932a76a09a6080d9dda81eb7822bdf0 Mon Sep 17 00:00:00 2001 From: Adam Bradley Date: Tue, 14 Sep 2021 12:56:59 -0500 Subject: [PATCH] react component docs --- README.md | 43 ++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 40 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 9c894686..c62d1770 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,8 @@ Partytown is a `5kb` library to help relocate resource intensive scripts into a - [Browser Features And Fallback](#browser-features-and-fallback) - [Usage](#usage) - [Partytown Library](#partytown-library) + - [React](#react) + - [Vanilla](#vanilla) - [Config](#config) - [Debugging](#debugging) - [Distribution](#distribution) @@ -174,17 +176,52 @@ Each third-party script that shouldn't run in the main thread, but instead party ``` -The Partytown library should be added to the bottom of the page and include the [async](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#attr-async) and [defer](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#attr-defer) attributes, which [helps tell the browser this is not a critical resource](https://developers.google.com/web/fundamentals/performance/optimizing-content-efficiency/loading-third-party-javascript#use_async_or_defer). +### React + +A React `` component is provided within [@builder.io/partytown/react](https://www.npmjs.com/package/@builder.io/partytown). The component is simply a wrapper to the [vanilla HTML](#vanilla) example below, and similarly should be added within the document's ``. Below is an example of the React `` component used within a [Next.js Document](https://nextjs.org/docs/advanced-features/custom-document). + +```jsx +import Document, { Html, Head, Main, NextScript } from 'next/document'; + +export default class MyDocument extends Document { + render() { + return ( + + + + + +
+ + + + ); + } +} +``` + +### Vanilla +To load Partytown with just HTML, the library script below should be added within the `` of page. The snippet will patch any global variables needed so other library scripts, such as Google Tag Manager's [Data Layer](https://developers.google.com/tag-manager/devguide), continues to work. However, the actual Partytown library, and any of the third-party scripts, are not downloaded or executed until after the document has loaded. + + ```html - + + + ``` -Note that this script _must_ be hosted from the same origin as the HTML page, rather than a CDN. Additionally, the Partytown library should be +Note that the loaded script _must_ be hosted from the same origin as the HTML page, rather than a CDN. Additionally, the Partytown library should be hosted from its own dedicated root directory `/~partytown/`. This root directory becomes the [scope](https://developers.google.com/web/ilt/pwa/introduction-to-service-worker#registration_and_scope) for the service worker, and all client-side requests within that path are intercepted by Partytown. With scripts disabled from executing, the Partytown library can lazily begin loading and executing the scripts from inside a worker. +### Copy Tasks + +An additional requirement is that the `/~partytown/` directory should serves the static files found within [@builder.io/partytown/lib](https://unpkg.com/browse/@builder.io/partytown/lib/). The quickest way is to just copy the JavaScript files to the public directory of your server. Another option would be to setup a copy task within the project's bundler, such as Webpack. + ### Config Before the Partytown library script, you can configure the `partytown` global object, such as: