docs: replace plugin updates (#14)

src/content/tutorial/vite-plugin/replace-plugin/defining-transform-hook/_solution/vite-plugin-replace.ts

@@ -1,7 +1,7 @@
 export default function vitePluginReplace() {
   return {
     name: "replace-plugin",
-    transform(src, id) {
+    transform(code, id) {
       if (id.includes("tutorial-example.js")) {
         return { code: "mountHTML('<h1>Changed!</h1>')" };
       }

src/content/tutorial/vite-plugin/replace-plugin/defining-transform-hook/content.md

@@ -1,12 +1,12 @@
 ---
 type: lesson
-title: Defining transform hook
+title: The transform hook
 focus: /vite-plugin-replace.ts
 ---
 
-# Transform hook
+# The transform hook
 
-Modifying contents of a source code file is called **transforming** in Vite. To do this in a Vite plugin, we'll need to use `transform` hook.
+Modifying the contents of a source code file is called **transforming** in Vite. To transform a module in a Vite plugin, we'll need to use `transform` hook.
 
 ```ts add={3}
 {
@@ -15,9 +15,9 @@ Modifying contents of a source code file is called **transforming** in Vite. To
 }
 ```
 
-This hooks is called with two options:
+This hook is called with two options:
 
-- `src` is the source code of the file, or the result of previous Vite plugin's transform
+- `code` is the source code of the file, or the result of previous Vite plugin's transform
 - `id` is the name of the module
 
 As return value Vite expects an object with various properties.
@@ -26,12 +26,12 @@ In this tutorial we'll skip most of them and focus only on `code` property. This
 ```ts
 {
   name: "replace-plugin",
-  transform(src, id) {
+  transform(code, id) {
     return { code: <transformed Javascript code> }
   }
 }
 ```
 
-In `tutorial-example.js` we have a helper function `mountHTML()`. It can be used to modify the page on preview tab. Try changing the contents of `tutorial-example.js` using `transform` hook so that `mountHTML` is called with `<h1>Changed!</h1>` instead.
+In `tutorial-example.js` we have a helper function `mountHTML()`. It can be used to modify the page on preview tab. Try changing the contents of `tutorial-example.js` using the `transform` hook so that `mountHTML` is called with `<h1>Changed!</h1>` instead.
 
-> 💡 Note that `transform` hook is called for every single file that Vite processes. Make sure to specifically transform only `tutorial-example.js`. This can be detected by checking `id` for matches exactly as we did with the `load` hook.
+> 💡 Note that the `transform` hook is called for every single module that Vite processes. Make sure to only transform `tutorial-example.js`. This can be detected by checking `id` for matches in the same way we did for the `load` hook in the previous chapter.

src/content/tutorial/vite-plugin/replace-plugin/summarize-replace-plugin/_files/vite-plugin-replace.ts

@@ -1,9 +1,9 @@
 export default function vitePluginReplace(options) {
   return {
     name: "replace-plugin",
-    transform(src, id) {
+    transform(code, id) {
       if (id.includes("tutorial-example.js")) {
-        return { code: src.replaceAll(options.from, options.to) };
+        return { code: code.replaceAll(options.from, options.to) };
       }
     }
   };

src/content/tutorial/vite-plugin/replace-plugin/summarize-replace-plugin/_solution/vite-plugin-replace.ts

@@ -1,9 +1,9 @@
 export default function vitePluginReplace(options) {
   return {
     name: "replace-plugin",
-    transform(src, id) {
+    transform(code, id) {
       if (id.includes("tutorial-example.js")) {
-        return { code: src.replaceAll(options.from, options.to) };
+        return { code: code.replaceAll(options.from, options.to) };
       }
     }
   };

src/content/tutorial/vite-plugin/replace-plugin/summarize-replace-plugin/content.md

@@ -6,18 +6,18 @@ focus: /vite.config.ts
 
 # Summarize
 
-We've now created a plugin that's able to transform our source code. The plugin is also stored in a separate file from the `vite.config.ts`. Let's summarize the process:
+We've now created a plugin that's able to transform our source code. The plugin is also defined in a separate file from the `vite.config.ts`. Let's summarize the process:
 
 <ol>
-  <li>The <code>vite.config.ts</code> imports custom plugin from separate file and calls it with plugin options</li>
+  <li>The <code>vite.config.ts</code> imports a custom plugin constructor from a separate module and calls it with plugin options</li>
 
-  <li class="mt2">Plugin intercepts <code>tutorial-example.js</code> in <code>transform</code> hook</li>
+  <li class="mt2">The Plugin intercepts <code>tutorial-example.js</code> in the <code>transform</code> hook</li>
 
-  <li class="mt2"><code>transform</code> hook uses plugin options with <code>String.replaceAll</code> and modifies the passed <code>src</code></li>
+  <li class="mt2">In the <code>transform</code> hook, we use the plugin options with <code>String.replaceAll</code> to modify the passed source <code>code</code></li>
 
-  <li class="mt2">Transformed code is returned from <code>transform</code> hook and browser loads the modified file&nbsp;✅</li>
+  <li class="mt2">Transformed code is returned from the <code>transform</code> hook and the browser loads the modified module&nbsp;✅</li>
 </ol>
 
 📚 Homework: Build a Vite plugin that replaces all usage of `process.env.<variable-name>` with the actual values during build.
 
-> 💡 Note that when transforming source code we should also process [source maps](https://web.dev/articles/source-maps). There's npm package [`magic-string`](https://www.npmjs.com/package/magic-string) that's widely used by Vite's internal and community plugins.
+> 💡 Note that when transforming source code we should also process [source maps](https://web.dev/articles/source-maps). There's npm package [`magic-string`](https://www.npmjs.com/package/magic-string) that's widely used by Vite's internals and community plugins.

src/content/tutorial/vite-plugin/replace-plugin/transforming-code/content.md

@@ -6,24 +6,24 @@ focus: /vite.config.ts
 
 # Vite Replace plugin
 
-In this part we'll create a plugin that modifies our source code. This plugin will look for specific patterns in the source files and replace those with the configured value.
+In this chapter we'll create a plugin that modifies loaded source code. This plugin will look for specific patterns in the source files and replace those with the configured value.
 
-For example, with configuration of `{ from: "Initial value", to: "Replaced value" }` this plugin should replace all occurences of `"Initial value"` with `"Replaced value"`.
+For example, when configured with `{ from: "Initial value", to: "Replaced value" }` this plugin should replace all occurrences of `"Initial value"` with `"Replaced value"`.
 
-The plugin will also be in a separate file from our `vite.config.ts`.
+The plugin will also be in a separate file from our `vite.config.ts`. Inlining plugins is ok for simple cases, but it is usual to abstract them using Plugin Constructors to keep our app configuration manageable as our plugins pipeline grows. These plugins can also be later packaged and published to npm to share them with other Vite users. You'll normally reach out for popular community plugins for common patterns, before building your own.
 
 ```
 ├── vite-plugin-replace.ts
 └── vite.config.ts
 ```
 
-To use this plugin we'll be importing it from the `vite-plugin-replace.ts` and passing it's return value to our Vite configuration's `plugins`.
+To use this plugin we'll be importing it from the `vite-plugin-replace.ts` module and passing it's return value to our Vite configuration's `plugins`.
 
 ```ts
 import replacePlugin from "./vite-plugin-replace";
 ```
 
-Options are passed to the plugin as function argument.
+`replacePlugin` is a plugin constructor. We'll call it with options to create a plugin instance.
 
 ```ts
 replacePlugin({
@@ -32,8 +32,8 @@ replacePlugin({
 });
 ```
 
-Import the plugin in `vite.config.ts` and pass it in `plugins`. The `vite-plugin-replace.ts` contains minimal plugin already.
+Import the plugin constructor in `vite.config.ts` and call it to add a new plugin in the `plugins` array. The `vite-plugin-replace.ts` contains a minimal plugin already.
 
-Preview tab should indicate successful load of the plugin:
+The preview tab should indicate a successful load of the plugin:
 
 > Loaded Vite plugins: replace-plugin ✅

src/content/tutorial/vite-plugin/replace-plugin/transforming-source-code/_files/vite-plugin-replace.ts

@@ -1,9 +1,9 @@
 export default function vitePluginReplace() {
   return {
     name: "replace-plugin",
-    transform(src, id) {
+    transform(code, id) {
       if (id.includes("tutorial-example.js")) {
-        return { code: src };
+        return { code };
       }
     }
   };

src/content/tutorial/vite-plugin/replace-plugin/transforming-source-code/_solution/vite-plugin-replace.ts

@@ -1,9 +1,9 @@
 export default function vitePluginReplace(options) {
   return {
     name: "replace-plugin",
-    transform(src, id) {
+    transform(code, id) {
       if (id.includes("tutorial-example.js")) {
-        return { code: src.replaceAll(options.from, options.to) };
+        return { code: code.replaceAll(options.from, options.to) };
       }
     }
   };

src/content/tutorial/vite-plugin/replace-plugin/transforming-source-code/content.md

@@ -6,7 +6,7 @@ focus: /vite-plugin-replace.ts
 
 # Transforming source code
 
-Now that we can use `transform` hook to return code for a requested module, let's try modifying the original source code of the module.
+Now that we can use the `transform` hook to return a new version of the code for a requested module, let's try modifying the original source code of the module.
 
 In the `vite.config.ts` we are passing the options for our plugin:
 
@@ -26,10 +26,10 @@ export default function vitePluginReplace() {
     name: "replace-plugin",
 ```
 
-Next we need to modify the `src` of `transform` hook with the options.
+Next we need to modify the `code` of `transform` hook with the options.
 
 ```ts
-src.replaceAll(options.from, options.to);
+code.replaceAll(options.from, options.to);
 ```
 
 Add these changes to the `vite-plugin-replace.ts` and set proper values for the plugin options in `vite.config.ts`, so that preview tab outputs `Replaced value!`.