JS file collocation with Razor components (#23327)

guardrex · web-flow · commit e5c703659d59 · 2021-09-16T10:48:26.000-05:00
diff --git a/aspnetcore/blazor/components/class-libraries.md b/aspnetcore/blazor/components/class-libraries.md
@@ -252,7 +252,7 @@ The distinction between using the `Link` component in a child component and plac
 * Can be modified by application state. A hard-coded `<link>` HTML tag can't be modified by application state.
 * Is removed from the HTML `<head>` when the parent component is no longer rendered.
 
-## Create an RCL with static assets
+## Create an RCL with static assets in the `wwwroot` folder
 
 An RCL's static assets are available to any app that consumes the library.
 
@@ -311,6 +311,10 @@ Rendered `Jeep` component:
 
 For more information, see <xref:razor-pages/ui-class#create-an-rcl-with-static-assets>.
 
+## Create an RCL with JavaScript files collocated with components
+
+[!INCLUDE[](~/includes/js-collocation.md)]
+
 ## Supply components and static assets to multiple hosted Blazor apps
 
 For more information, see <xref:blazor/host-and-deploy/webassembly#static-assets-and-class-libraries-for-multiple-blazor-webassembly-apps>.
diff --git a/aspnetcore/blazor/javascript-interoperability/index.md b/aspnetcore/blazor/javascript-interoperability/index.md
@@ -40,7 +40,8 @@ Load JavaScript (JS) code using any of the following approaches:
 
 * [Load a script in `<head>` markup](#load-a-script-in-head-markup) (*Not generally recommended*)
 * [Load a script in `<body>` markup](#load-a-script-in-body-markup)
-* [Load a script from an external JS file (`.js`)](#load-a-script-from-an-external-js-file-js)
+* [Load a script from an external JavaScript file (`.js`) collocated with a component](#load-a-script-from-an-external-javascript-file-js-collocated-with-a-component)
+* [Load a script from an external JavaScript file (`.js`)](#load-a-script-from-an-external-javascript-file-js)
 * [Inject a script after Blazor starts](#inject-a-script-after-blazor-starts)
 
 > [!WARNING]
@@ -53,7 +54,7 @@ Load JavaScript (JS) code using any of the following approaches:
 
 *The approach in this section isn't generally recommended.*
 
-Place the script  (`<script>...</script>`) in the `<head>` element markup of `wwwroot/index.html` (Blazor WebAssembly) or `Pages/_Layout.cshtml` (Blazor Server):
+Place the JavaScript (JS) tags (`<script>...</script>`) in the `<head>` element markup of `wwwroot/index.html` (Blazor WebAssembly) or `Pages/_Layout.cshtml` (Blazor Server):
 
 ```html
 <head>
@@ -74,7 +75,7 @@ Loading JS from the `<head>` isn't the best approach for the following reasons:
 
 ### Load a script in `<body>` markup
 
-Place the script  (`<script>...</script>`) inside the closing `</body>` element markup of `wwwroot/index.html` (Blazor WebAssembly) or `Pages/_Layout.cshtml` (Blazor Server):
+Place the JavaScript (JS) tags (`<script>...</script>`) inside the closing `</body>` element markup of `wwwroot/index.html` (Blazor WebAssembly) or `Pages/_Layout.cshtml` (Blazor Server):
 
 ```html
 <body>
@@ -91,9 +92,15 @@ Place the script  (`<script>...</script>`) inside the closing `</body>` element
 
 The `{webassembly|server}` placeholder in the preceding markup is either `webassembly` for a Blazor WebAssembly app (`blazor.webassembly.js`) or `server` for a Blazor Server app (`blazor.server.js`).
 
-### Load a script from an external JS file (`.js`)
+### Load a script from an external JavaScript file (`.js`) collocated with a component
 
-Place the script  (`<script>...</script>`) with a script `src` path inside the closing `</body>` tag after the Blazor script reference.
+[!INCLUDE[](~/includes/js-collocation.md)]
+
+For more information on RCLs, see <xref:blazor/components/class-libraries>.
+
+### Load a script from an external JavaScript file (`.js`)
+
+Place the JavaScript (JS) tags (`<script>...</script>`) with a script source (`src`) path inside the closing `</body>` tag after the Blazor script reference.
 
 In `wwwroot/index.html` (Blazor WebAssembly) or `Pages/_Layout.cshtml` (Blazor Server):
 
diff --git a/aspnetcore/includes/js-collocation.md b/aspnetcore/includes/js-collocation.md
@@ -0,0 +1,49 @@
+---
+no-loc: [Home, Privacy, Kestrel, appsettings.json, "ASP.NET Core Identity", cookie, Cookie, Blazor, "Blazor Server", "Blazor WebAssembly", "Identity", "Let's Encrypt", Razor, SignalR]
+---
+Collocation of JavaScript (JS) files for pages, views, and Razor components is a convenient way to organize scripts in an app.
+
+Collocate JS files using the following filename extension conventions:
+
+* Pages of Razor Pages apps and views of MVC apps: `.cshtml.js`. Examples:
+  * `Pages/Contact.cshtml.js` for the `Contact` page of a Razor Pages app at `Pages/Contact.cshtml`.
+  * `Views/Home/Contact.cshtml.js` for the `Contact` view of an MVC app at `Views/Home/Contact.cshtml`.
+* Razor components of Blazor apps: `.razor.js`. Example: `Pages/Index.razor.js` for the `Index` component at `Pages/Index.razor`.
+
+Collocated JS files are publicly addressable using the path to the file in the project:
+
+* Pages, views, and components from a collocated scripts file in the app:
+
+  `{PATH}/{PAGE, VIEW, OR COMPONENT}.{EXTENSION}`
+  
+  * The `{PATH}` placeholder is the path to the page, view, or component.
+  * The `{PAGE, VIEW, OR COMPONENT}` placeholder is the page, view, or component.
+  * The `{EXTENSION}` placeholder matches the extension of the page, view, or component, either `razor` or `cshtml`, followed by `.js`.
+  
+  In the following example from a Razor Pages app, the script is collocated in the `Pages` folder with the `Contact` page (`Pages/Contact.cshtml`):
+
+  ```razor
+  @section Scripts {
+    <script src="~/Pages/Contact.cshtml.js"></script>
+  }
+  ```
+
+* For scripts provided by a Razor class library (RCL):
+
+  `_content/{PACKAGE ID}/{PATH}/{PAGE, VIEW, OR COMPONENT}.{EXTENSION}`
+
+  * The `{PACKAGE ID}` placeholder is the RCL's package identifier (or library name for a class library referenced by the app).
+  * The `{PATH}` placeholder is the path to the page, view, or component. If a Razor component is located at the root of the RCL, the path segment isn't included.
+  * The `{PAGE, VIEW, OR COMPONENT}` placeholder is the page, view, or component.
+  * The `{EXTENSION}` placeholder matches the extension of page, view, or component, either `razor` or `cshtml`, followed by `.js`.
+
+  In the following Blazor app example:
+  
+  * The RCL's package identifier is `AppJS`.
+  * A module's scripts are loaded for the `Index` component (`Index.razor`).
+  * The `Index` component is in the `Pages` folder of the RCL.
+
+  ```csharp
+  var module = await JS.InvokeAsync<IJSObjectReference>("import", 
+      "_content/AppJS/Pages/Index.razor.js");
+  ```
