Skip to content

Improve JavaScript colocation guidance #24654

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
guardrex merged 2 commits into from
Jan 18, 2022
Merged

Improve JavaScript colocation guidance #24654

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
15302c4
Improve JavaScript colocation guidance
guardrex Jan 18, 2022
9c6b0db
Updates
guardrex Jan 18, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 12 additions & 11 deletions aspnetcore/blazor/javascript-interoperability/call-dotnet-from-javascript.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -295,6 +295,17 @@ For information on isolating scripts in [JS modules](https://developer.mozilla.o
> [!WARNING]
> Don't place a `<script>` tag in a component file (`.razor`) because the `<script>` tag can't be updated dynamically.

## JavaScript isolation in JavaScript modules

Blazor enables JavaScript (JS) isolation in standard [JavaScript modules](https://developer.mozilla.org/docs/Web/JavaScript/Guide/Modules) ([ECMAScript specification](https://tc39.es/ecma262/#sec-modules)).

JS isolation provides the following benefits:

* Imported JS no longer pollutes the global namespace.
* Consumers of a library and components aren't required to import the related JS.

For more information, see <xref:blazor/js-interop/call-javascript-from-dotnet#javascript-isolation-in-javascript-modules>.

## Avoid circular object references

Objects that contain circular references can't be serialized on the client for either:
Expand Down Expand Up @@ -396,17 +407,6 @@ In the preceding example:

[!INCLUDE[](~/blazor/includes/js-interop/6.0/size-limits.md)]

## JavaScript isolation in JavaScript modules

Blazor enables JavaScript (JS) isolation in standard [JavaScript modules](https://developer.mozilla.org/docs/Web/JavaScript/Guide/Modules) ([ECMAScript specification](https://tc39.es/ecma262/#sec-modules)).

JS isolation provides the following benefits:

* Imported JS no longer pollutes the global namespace.
* Consumers of a library and components aren't required to import the related JS.

For more information, see <xref:blazor/js-interop/call-javascript-from-dotnet#javascript-isolation-in-javascript-modules>.

## Additional resources

* <xref:blazor/js-interop/call-javascript-from-dotnet>
Expand Down Expand Up @@ -691,6 +691,7 @@ Load JavaScript (JS) code using any of approaches described by the [JS interop o

* [Load a script in `<head>` markup](xref:blazor/js-interop/index#load-a-script-in-head-markup) (*Not generally recommended*)
* [Load a script in `<body>` markup](xref:blazor/js-interop/index#load-a-script-in-body-markup)
* [Load a script from an external JavaScript file (`.js`) collocated with a component](xref:blazor/js-interop/index#load-a-script-from-an-external-javascript-file-js-collocated-with-a-component)
* [Load a script from an external JS file (`.js`)](xref:blazor/js-interop/index#load-a-script-from-an-external-js-file-js)
* [Inject a script after Blazor starts](xref:blazor/js-interop/index#inject-a-script-after-blazor-starts)

Expand Down
1 change: 1 addition & 0 deletions aspnetcore/blazor/javascript-interoperability/call-javascript-from-dotnet.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,7 @@ Load JavaScript (JS) code using any of approaches described by the [JavaScript (

* [Load a script in `<head>` markup](xref:blazor/js-interop/index#load-a-script-in-head-markup) (*Not generally recommended*)
* [Load a script in `<body>` markup](xref:blazor/js-interop/index#load-a-script-in-body-markup)
* [Load a script from an external JavaScript file (`.js`) collocated with a component](xref:blazor/js-interop/index#load-a-script-from-an-external-javascript-file-js-collocated-with-a-component)
* [Load a script from an external JS file (`.js`)](xref:blazor/js-interop/index#load-a-script-from-an-external-js-file-js)
* [Inject a script after Blazor starts](xref:blazor/js-interop/index#inject-a-script-after-blazor-starts)

Expand Down
45 changes: 35 additions & 10 deletions aspnetcore/includes/js-collocation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,36 +6,61 @@ Collocation of JavaScript (JS) files for pages, views, and Razor components is a
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`.
* `Pages/Index.cshtml.js` for the `Index` page of a Razor Pages app at `Pages/Index.cshtml`.
* `Views/Home/Index.cshtml.js` for the `Index` view of an MVC app at `Views/Home/Index.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:
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}`
`{PATH}/{PAGE, VIEW, OR COMPONENT}.{EXTENSION}.js`

* 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`):
* The `{EXTENSION}` placeholder matches the extension of the page, view, or component, either `razor` or `cshtml`.

Razor Pages example:

A JS file for the `Index` page is placed in the `Pages` folder (`Pages/Index.cshtml.js`) next to the `Index` page (`Pages/Index.cshtml`). In the `Index` page, the script is referenced at the path in the `Pages` folder:

```razor
@section Scripts {
<script src="~/Pages/Contact.cshtml.js"></script>
<script src="~/Pages/Index.cshtml.js"></script>
}
```

When the app is published, the framework automatically moves the script to the web root. In the preceding example, the script is moved to `bin\Release\{TARGET FRAMEWORK MONIKER}\publish\wwwroot\Pages\Index.cshtml.js`, where the `{TARGET FRAMEWORK MONIKER}` placeholder is the [Target Framework Moniker (TFM)](/dotnet/standard/frameworks). No change is required to the script's relative URL in the `Index` page.

Blazor example:

A JS file for the `Index` component is placed in the `Pages` folder (`Pages/Index.razor.js`) next to the `Index` component (`Pages/Index.razor`). In the `Index` component, the script is referenced at the path in the `Pages` folder. The following example is based on an example shown in the <xref:blazor/js-interop/call-javascript-from-dotnet#javascript-isolation-in-javascript-modules> article.

`Pages/Index.razor.js`:

```javascript
export function showPrompt(message) {
return prompt(message, 'Type anything here');
}
```

In the `OnAfterRenderAsync` method of the `Index` component (`Pages/Index.razor`):

```razor
module = await JS.InvokeAsync<IJSObjectReference>(
"import", "./Pages/Index.razor.js");
```

When the app is published, the framework automatically moves the script to the web root. In the preceding example, the script is moved to `bin\Release\{TARGET FRAMEWORK MONIKER}\publish\wwwroot\Pages\Index.razor.js`, where the `{TARGET FRAMEWORK MONIKER}` placeholder is the [Target Framework Moniker (TFM)](/dotnet/standard/frameworks). No change is required to the script's relative URL in the `Index` component.

* For scripts provided by a Razor class library (RCL):

`_content/{PACKAGE ID}/{PATH}/{PAGE, VIEW, OR COMPONENT}.{EXTENSION}`
`_content/{PACKAGE ID}/{PATH}/{PAGE, VIEW, OR COMPONENT}.{EXTENSION}.js`

* 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`.
* The `{EXTENSION}` placeholder matches the extension of page, view, or component, either `razor` or `cshtml`.

In the following Blazor app example:

Expand Down