docs(turbo-tasks): Improve RcStr docs

[bgw]

Discussion with @unstubbable was that he didn't know if he should use String or RcStr. This should clarify what people should use, why, and how to construct the RcStr.

Closes PACK-3468

[bgw]

• docs(turbo-tasks): Improve RcStr docs #72825 👈 (View in Graphite)
• canary

This stack of pull requests is managed by Graphite. Learn more about stacking.

[unstubbable]

Thank you!

[ijjk]

Stats from current PR

Default Build (Increase detected ⚠️)

General

	vercel/next.js canary	vercel/next.js bgw/rcstr-docs	Change
buildDuration	21.4s	21.9s	⚠️ +505ms
buildDurationCached	16.6s	14.5s	N/A
nodeModulesSize	403 MB	402 MB	N/A
nextStartRea..uration (ms)	473ms	485ms	N/A

Client Bundles (main, webpack)

	vercel/next.js canary	vercel/next.js bgw/rcstr-docs	Change
3323-HASH.js gzip	45.8 kB	45.6 kB	N/A
43344b9e-HASH.js gzip	52.6 kB	52.5 kB	N/A
441-HASH.js gzip	5.26 kB	5.26 kB	N/A
6624.HASH.js gzip	169 B	169 B	✓
framework-HASH.js gzip	57.3 kB	57.3 kB	N/A
main-app-HASH.js gzip	232 B	234 B	N/A
main-HASH.js gzip	33.2 kB	33.2 kB	N/A
webpack-HASH.js gzip	1.71 kB	1.71 kB	N/A
Overall change	169 B	169 B	✓

Legacy Client Bundles (polyfills)

	vercel/next.js canary	vercel/next.js bgw/rcstr-docs	Change
polyfills-HASH.js gzip	39.4 kB	39.4 kB	✓
Overall change	39.4 kB	39.4 kB	✓

Client Pages

	vercel/next.js canary	vercel/next.js bgw/rcstr-docs	Change
_app-HASH.js gzip	193 B	193 B	✓
_error-HASH.js gzip	192 B	192 B	✓
amp-HASH.js gzip	512 B	512 B	✓
css-HASH.js gzip	339 B	342 B	N/A
dynamic-HASH.js gzip	1.84 kB	1.84 kB	N/A
edge-ssr-HASH.js gzip	265 B	265 B	✓
head-HASH.js gzip	364 B	365 B	N/A
hooks-HASH.js gzip	393 B	393 B	✓
image-HASH.js gzip	4.41 kB	4.41 kB	N/A
index-HASH.js gzip	268 B	269 B	N/A
link-HASH.js gzip	2.78 kB	2.78 kB	N/A
routerDirect..HASH.js gzip	328 B	326 B	N/A
script-HASH.js gzip	397 B	395 B	N/A
withRouter-HASH.js gzip	325 B	323 B	N/A
1afbb74e6ecf..834.css gzip	106 B	106 B	✓
Overall change	1.66 kB	1.66 kB	✓

Client Build Manifests

	vercel/next.js canary	vercel/next.js bgw/rcstr-docs	Change
_buildManifest.js gzip	749 B	749 B	✓
Overall change	749 B	749 B	✓

Rendered Page Sizes

	vercel/next.js canary	vercel/next.js bgw/rcstr-docs	Change
index.html gzip	522 B	522 B	✓
link.html gzip	537 B	540 B	N/A
withRouter.html gzip	519 B	518 B	N/A
Overall change	522 B	522 B	✓

Edge SSR bundle Size

	vercel/next.js canary	vercel/next.js bgw/rcstr-docs	Change
edge-ssr.js gzip	128 kB	128 kB	N/A
page.js gzip	198 kB	198 kB	N/A
Overall change	0 B	0 B	✓

Middleware size

	vercel/next.js canary	vercel/next.js bgw/rcstr-docs	Change
middleware-b..fest.js gzip	668 B	670 B	N/A
middleware-r..fest.js gzip	156 B	156 B	✓
middleware.js gzip	31 kB	31 kB	N/A
edge-runtime..pack.js gzip	844 B	844 B	✓
Overall change	1 kB	1 kB	✓

Next Runtimes

	vercel/next.js canary	vercel/next.js bgw/rcstr-docs	Change
196-experime...dev.js gzip	322 B	322 B	✓
196.runtime.dev.js gzip	314 B	314 B	✓
app-page-exp...dev.js gzip	320 kB	319 kB	N/A
app-page-exp..prod.js gzip	123 kB	123 kB	✓
app-page-tur..prod.js gzip	136 kB	136 kB	✓
app-page-tur..prod.js gzip	131 kB	131 kB	N/A
app-page.run...dev.js gzip	310 kB	309 kB	N/A
app-page.run..prod.js gzip	119 kB	119 kB	N/A
app-route-ex...dev.js gzip	36 kB	36 kB	N/A
app-route-ex..prod.js gzip	24.4 kB	24.4 kB	N/A
app-route-tu..prod.js gzip	24.4 kB	24.4 kB	N/A
app-route-tu..prod.js gzip	24.2 kB	24.2 kB	N/A
app-route.ru...dev.js gzip	37.6 kB	37.6 kB	N/A
app-route.ru..prod.js gzip	24.2 kB	24.2 kB	N/A
pages-api-tu..prod.js gzip	9.59 kB	9.59 kB	✓
pages-api.ru...dev.js gzip	11.4 kB	11.4 kB	✓
pages-api.ru..prod.js gzip	9.58 kB	9.58 kB	✓
pages-turbo...prod.js gzip	20.9 kB	20.9 kB	✓
pages.runtim...dev.js gzip	26.5 kB	26.5 kB	✓
pages.runtim..prod.js gzip	20.9 kB	20.9 kB	✓
server.runti..prod.js gzip	916 kB	916 kB	N/A
Overall change	358 kB	358 kB	✓

build cache Overall increase ⚠️

	vercel/next.js canary	vercel/next.js bgw/rcstr-docs	Change
0.pack gzip	2.01 MB	2.01 MB	⚠️ +2.6 kB
index.pack gzip	145 kB	146 kB	⚠️ +773 B
Overall change	2.15 MB	2.16 MB	⚠️ +3.38 kB

Diff details

Diff for page.js

Diff too large to display

Diff for middleware.js

Diff too large to display

Diff for edge-ssr.js

Diff too large to display

Diff for dynamic-HASH.js

@@ -1,7 +1,7 @@
 (self["webpackChunk_N_E"] = self["webpackChunk_N_E"] || []).push([
   [2291],
   {
-    /***/ 8725: /***/ (
+    /***/ 4162: /***/ (
       __unused_webpack_module,
       __unused_webpack_exports,
       __webpack_require__
@@ -9,7 +9,7 @@
       (window.__NEXT_P = window.__NEXT_P || []).push([
         "/dynamic",
         function () {
-          return __webpack_require__(2589);
+          return __webpack_require__(6810);
         },
       ]);
       if (false) {
@@ -18,7 +18,7 @@
       /***/
     },
 
-    /***/ 2081: /***/ (module, exports, __webpack_require__) => {
+    /***/ 9181: /***/ (module, exports, __webpack_require__) => {
       "use strict";
 
       Object.defineProperty(exports, "__esModule", {
@@ -51,7 +51,7 @@
         __webpack_require__(3017)
       );
       const _loadablesharedruntime = /*#__PURE__*/ _interop_require_default._(
-        __webpack_require__(6846)
+        __webpack_require__(9922)
       );
       const isServerSide = "object" === "undefined";
       // Normalize loader to return the module as form { default: Component } for `React.lazy`.
@@ -152,11 +152,7 @@
       /***/
     },
 
-    /***/ 880: /***/ (
-      __unused_webpack_module,
-      exports,
-      __webpack_require__
-    ) => {
+    /***/ 84: /***/ (__unused_webpack_module, exports, __webpack_require__) => {
       "use strict";
       /* __next_internal_client_entry_do_not_use__  cjs */
       Object.defineProperty(exports, "__esModule", {
@@ -179,7 +175,7 @@
       /***/
     },
 
-    /***/ 6846: /***/ (
+    /***/ 9922: /***/ (
       __unused_webpack_module,
       exports,
       __webpack_require__
@@ -221,7 +217,7 @@ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE
       const _react = /*#__PURE__*/ _interop_require_default._(
         __webpack_require__(3017)
       );
-      const _loadablecontextsharedruntime = __webpack_require__(880);
+      const _loadablecontextsharedruntime = __webpack_require__(84);
       function resolve(obj) {
         return obj && obj.default ? obj.default : obj;
       }
@@ -456,7 +452,7 @@ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE
       /***/
     },
 
-    /***/ 2589: /***/ (
+    /***/ 6810: /***/ (
       __unused_webpack_module,
       __webpack_exports__,
       __webpack_require__
@@ -471,7 +467,7 @@ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE
       /* harmony import */ var react_jsx_runtime__WEBPACK_IMPORTED_MODULE_0__ =
         __webpack_require__(9901);
       /* harmony import */ var next_dynamic__WEBPACK_IMPORTED_MODULE_1__ =
-        __webpack_require__(4032);
+        __webpack_require__(8187);
       /* harmony import */ var next_dynamic__WEBPACK_IMPORTED_MODULE_1___default =
         /*#__PURE__*/ __webpack_require__.n(
           next_dynamic__WEBPACK_IMPORTED_MODULE_1__
@@ -480,12 +476,12 @@ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE
       const DynamicHello = next_dynamic__WEBPACK_IMPORTED_MODULE_1___default()(
         () =>
           __webpack_require__
-            .e(/* import() */ 6624)
-            .then(__webpack_require__.bind(__webpack_require__, 6624))
+            .e(/* import() */ 9173)
+            .then(__webpack_require__.bind(__webpack_require__, 9173))
             .then((mod) => mod.Hello),
         {
           loadableGenerated: {
-            webpack: () => [/*require.resolve*/ 6624],
+            webpack: () => [/*require.resolve*/ 9173],
           },
         }
       );
@@ -512,12 +508,12 @@ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE
       /***/
     },
 
-    /***/ 4032: /***/ (
+    /***/ 8187: /***/ (
       module,
       __unused_webpack_exports,
       __webpack_require__
     ) => {
-      module.exports = __webpack_require__(2081);
+      module.exports = __webpack_require__(9181);
 
       /***/
     },
@@ -527,7 +523,7 @@ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE
     /******/ var __webpack_exec__ = (moduleId) =>
       __webpack_require__((__webpack_require__.s = moduleId));
     /******/ __webpack_require__.O(0, [636, 6593, 8792], () =>
-      __webpack_exec__(8725)
+      __webpack_exec__(4162)
     );
     /******/ var __webpack_exports__ = __webpack_require__.O();
     /******/ _N_E = __webpack_exports__;

Diff for image-HASH.js

@@ -1,7 +1,7 @@
 (self["webpackChunk_N_E"] = self["webpackChunk_N_E"] || []).push([
   [2983],
   {
-    /***/ 8493: /***/ (
+    /***/ 5118: /***/ (
       __unused_webpack_module,
       __unused_webpack_exports,
       __webpack_require__
@@ -9,7 +9,7 @@
       (window.__NEXT_P = window.__NEXT_P || []).push([
         "/image",
         function () {
-          return __webpack_require__(9071);
+          return __webpack_require__(865);
         },
       ]);
       if (false) {
@@ -18,7 +18,7 @@
       /***/
     },
 
-    /***/ 3317: /***/ (module, exports, __webpack_require__) => {
+    /***/ 2465: /***/ (module, exports, __webpack_require__) => {
       "use strict";
       /* __next_internal_client_entry_do_not_use__  cjs */
       Object.defineProperty(exports, "__esModule", {
@@ -40,17 +40,17 @@
         __webpack_require__(5993)
       );
       const _head = /*#__PURE__*/ _interop_require_default._(
-        __webpack_require__(3568)
+        __webpack_require__(2124)
       );
-      const _getimgprops = __webpack_require__(4193);
-      const _imageconfig = __webpack_require__(5388);
-      const _imageconfigcontextsharedruntime = __webpack_require__(7862);
-      const _warnonce = __webpack_require__(8332);
-      const _routercontextsharedruntime = __webpack_require__(7151);
+      const _getimgprops = __webpack_require__(3525);
+      const _imageconfig = __webpack_require__(7256);
+      const _imageconfigcontextsharedruntime = __webpack_require__(9122);
+      const _warnonce = __webpack_require__(6976);
+      const _routercontextsharedruntime = __webpack_require__(4955);
       const _imageloader = /*#__PURE__*/ _interop_require_default._(
-        __webpack_require__(3997)
+        __webpack_require__(617)
       );
-      const _usemergedref = __webpack_require__(1986);
+      const _usemergedref = __webpack_require__(1798);
       // This is replaced by webpack define plugin
       const configEnv = {
         deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
@@ -371,7 +371,7 @@
       /***/
     },
 
-    /***/ 1986: /***/ (module, exports, __webpack_require__) => {
+    /***/ 1798: /***/ (module, exports, __webpack_require__) => {
       "use strict";
 
       Object.defineProperty(exports, "__esModule", {
@@ -432,7 +432,7 @@
       /***/
     },
 
-    /***/ 4193: /***/ (
+    /***/ 3525: /***/ (
       __unused_webpack_module,
       exports,
       __webpack_require__
@@ -448,9 +448,9 @@
           return getImgProps;
         },
       });
-      const _warnonce = __webpack_require__(8332);
-      const _imageblursvg = __webpack_require__(2200);
-      const _imageconfig = __webpack_require__(5388);
+      const _warnonce = __webpack_require__(6976);
+      const _imageblursvg = __webpack_require__(8364);
+      const _imageconfig = __webpack_require__(7256);
       const VALID_LOADING_VALUES =
         /* unused pure expression or super */ null && [
           "lazy",
@@ -824,7 +824,7 @@
       /***/
     },
 
-    /***/ 2200: /***/ (__unused_webpack_module, exports) => {
+    /***/ 8364: /***/ (__unused_webpack_module, exports) => {
       "use strict";
       /**
        * A shared function, used on both client and server, to generate a SVG blur placeholder.
@@ -879,7 +879,7 @@
       /***/
     },
 
-    /***/ 6797: /***/ (
+    /***/ 9185: /***/ (
       __unused_webpack_module,
       exports,
       __webpack_require__
@@ -906,10 +906,10 @@
         },
       });
       const _interop_require_default = __webpack_require__(1739);
-      const _getimgprops = __webpack_require__(4193);
-      const _imagecomponent = __webpack_require__(3317);
+      const _getimgprops = __webpack_require__(3525);
+      const _imagecomponent = __webpack_require__(2465);
       const _imageloader = /*#__PURE__*/ _interop_require_default._(
-        __webpack_require__(3997)
+        __webpack_require__(617)
       );
       function getImageProps(imgProps) {
         const { props } = (0, _getimgprops.getImgProps)(imgProps, {
@@ -941,7 +941,7 @@
       /***/
     },
 
-    /***/ 3997: /***/ (__unused_webpack_module, exports) => {
+    /***/ 617: /***/ (__unused_webpack_module, exports) => {
       "use strict";
 
       Object.defineProperty(exports, "__esModule", {
@@ -976,7 +976,7 @@
       /***/
     },
 
-    /***/ 9071: /***/ (
+    /***/ 865: /***/ (
       __unused_webpack_module,
       __webpack_exports__,
       __webpack_require__
@@ -993,8 +993,8 @@
 
       // EXTERNAL MODULE: ./node_modules/.pnpm/[email protected]/node_modules/react/jsx-runtime.js
       var jsx_runtime = __webpack_require__(9901);
-      // EXTERNAL MODULE: ./node_modules/.pnpm/next@file+..+main-repo+packages+next+next-packed.tgz_react-dom@19.0.0-rc-5c56b873-20241107_re_4mwva3jlwiucd47fxfib3s2p5u/node_modules/next/image.js
-      var next_image = __webpack_require__(9384);
+      // EXTERNAL MODULE: ./node_modules/.pnpm/next@file+..+diff-repo+packages+next+next-packed.tgz_react-dom@19.0.0-rc-5c56b873-20241107_re_zlwfy6bhevrbsruir3sxzwvepy/node_modules/next/image.js
+      var next_image = __webpack_require__(6523);
       var image_default = /*#__PURE__*/ __webpack_require__.n(next_image); // ./pages/nextjs.png
       /* harmony default export */ const nextjs = {
         src: "/_next/static/media/nextjs.cae0b805.png",
@@ -1024,12 +1024,12 @@
       /***/
     },
 
-    /***/ 9384: /***/ (
+    /***/ 6523: /***/ (
       module,
       __unused_webpack_exports,
       __webpack_require__
     ) => {
-      module.exports = __webpack_require__(6797);
+      module.exports = __webpack_require__(9185);
 
       /***/
     },
@@ -1039,7 +1039,7 @@
     /******/ var __webpack_exec__ = (moduleId) =>
       __webpack_require__((__webpack_require__.s = moduleId));
     /******/ __webpack_require__.O(0, [636, 6593, 8792], () =>
-      __webpack_exec__(8493)
+      __webpack_exec__(5118)
     );
     /******/ var __webpack_exports__ = __webpack_require__.O();
     /******/ _N_E = __webpack_exports__;

Diff for 3323-HASH.js

Diff too large to display

Diff for 43344b9e-HASH.js

Diff too large to display

Diff for app-page-exp..ntime.dev.js

failed to diff

Diff for app-page-exp..time.prod.js

Diff too large to display

Diff for app-page-tur..time.prod.js

Diff too large to display

Diff for app-page-tur..time.prod.js

Diff too large to display

Diff for app-page.runtime.dev.js

failed to diff

Diff for app-page.runtime.prod.js

Diff too large to display

Diff for server.runtime.prod.js

failed to diff

Commit: 2664ddb