Implementation of hoisted scripts (#1178)

* Implementation of hoisted scripts

* Use the facade id

* Adds docs on hoisted scripts

* Don't try to run rollup if there are no hoisted scripts

* Handle scripts possibly being undefined (client:only)

* Get rid of changes to the portfolio example

* Adds a changeset

* Remove a todo

* Fix lint errors

* Rename TransformResult property to hoistedScripts

* Move Hoisted Scripts docs to astro-components page

* Fixes lint errors

* Fix path join for windows

1 files changed, 33 insertions, 0 deletions

diff --git a/docs/src/pages/core-concepts/astro-components.md b/docs/src/pages/core-concepts/astro-components.md
index 1faa65d0f..2747b33cb 100644
--- a/docs/src/pages/core-concepts/astro-components.md
+++ b/docs/src/pages/core-concepts/astro-components.md
@@ -275,6 +275,39 @@ const items = ["Dog", "Cat", "Platipus"];
 </ul>
 ```
 
+### Hoisted scripts
+
+By default Astro does not make any assumptions on how you want scripts to be served, so if you add a `<script>` tag in a page or a component it will be left alone.
+
+However if you'd like all of your scripts to be hoisted out of components and moved to the top of the page, and then later bundled together in production, you can achieve this with hoisted scripts.
+
+A __hoisted script__ looks like this:
+
+```astro
+<script hoist>
+  // An inline script
+</script>
+```
+
+Or it can link to an external JavaScript file:
+
+```astro
+<script src={Astro.resolve('./my-component.js')} hoist></script>
+```
+
+A hoisted script can be within a page or a component, and no matter how many times the component is used, the script will only be added once:
+
+```astro
+---
+import TwitterTimeline from '../components/TwitterTimeline.astro';
+---
+
+<-- The script will only be injected into the head once. -->
+<TwitterTimeline />
+<TwitterTimeline />
+<TwitterTimeline />
+```
+
 ## Comparing `.astro` versus `.jsx`
 
 `.astro` files can end up looking very similar to `.jsx` files, but there are a few key differences. Here's a comparison between the two formats.