Skip to content

Commit

Permalink
update script behavior section (#6798)
Browse files Browse the repository at this point in the history
Co-authored-by: Martin Trapp <94928215+martrapp@users.noreply.github.com>
Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com>
Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>
  • Loading branch information
4 people authored Mar 9, 2024
1 parent 455f62f commit 9235649
Showing 1 changed file with 24 additions and 3 deletions.
27 changes: 24 additions & 3 deletions src/content/docs/en/guides/view-transitions.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -453,11 +453,33 @@ When using the `<ViewTransitions />` router, the following steps occur to produc
7. The router executes any new scripts added to the page.
8. The `astro:page-load` event fires. This is the end of the navigation process.

## Script behavior during page navigation
## Script behavior with view transitions

When you add view transitions to an existing Astro project, some of your scripts may no longer re-run after page navigation like they did with full-page browser refreshes. Use the following information to ensure that your scripts execute as expected.

### Script order

When navigating between pages with the `<ViewTransitions />` component, scripts are run in sequential order to match browser behavior.

If you have code that sets up global state, this state will need to take into account that the script might execute more than once. Check for the global state in your `<script>` tag, and conditionally execute your code where possible:
### Script re-execution

[Bundled module scripts](/en/guides/client-side-scripts/#script-processing), which are the default scripts in Astro, are only ever executed once. After initial execution they will be ignored, even if the script exists on the new page after a transition.

Unlike bundled module scripts, [inline scripts](/en/guides/client-side-scripts/#opting-out-of-processing) have the potential to be re-executed during a user's visit to a site if they exist on a page that is visited multiple times. Inline scripts might also re-execute when a visitor navigates to a page without the script, and then back to one with the script.

#### `data-astro-rerun`

<p><Since v="4.5.0" /></p>

To force inline scripts to re-execute after every transition, add the `data-astro-rerun` property. Adding any attribute to a script also implicitly adds `is:inline`, so this is only available for scripts that are not bundled and processed by Astro.

```astro
<script is:inline data-astro-rerun>...</script>
```

To ensure that a script runs every time a page is loaded during client-side navigation, it should be executed by a [lifecycle event](#lifecycle-events). For example, event listeners for `DOMContentLoaded` can be replaced by the [`astro:page-load`](/en/guides/view-transitions/#astropage-load) lifecycle event.

If you have code that sets up a global state in an inline script, this state will need to take into account that the script might execute more than once. Check for the global state in your `<script>` tag, and conditionally execute your code where possible. This works because `window` is preserved.

```astro
<script is:inline>
Expand All @@ -467,7 +489,6 @@ If you have code that sets up global state, this state will need to take into ac
</script>
```

Module scripts, including those that add event listeners for `DOMContentLoaded`, are only ever executed once because the browser keeps track of which modules are already loaded. You must add listeners for a [Lifecycle event](#lifecycle-events) to re-execute scripts during client-side page navigation.

See the [Add View Transitions Tutorial](/en/tutorials/add-view-transitions/#update-scripts) for an example of updating existing scripts in a project.

Expand Down

0 comments on commit 9235649

Please sign in to comment.