deprecate Astro.canonicalURL, add Astro.url

src/pages/en/migrate.md

@@ -9,6 +9,31 @@ This guide will help you migrate from older versions of Astro to the latest vers
 
 Read the guide below for major highlights and instructions on how to handle breaking changes.
 
+## Upcoming Astro 1.0 Release Candidate
+
+We plan to release an Astro v1.0 Release Candidate (RC) sometime in the next several days. This version is not yet available to most users, however you can try it yourself today by running this command:
+
+```
+npm install astro@next--rc
+```
+
+Below are the changes that you should be aware of when migrating to the Astro v1.0 RC.
+
+### Updated: Vite 3
+
+Astro v1.0 RC has upgraded from Vite 2 to [Vite 3](https://vitejs.dev/). We've handled most of the upgrade for you inside of Astro, however some subtle Vite behaviors may still change between versions. Refer to the official [Vite Migration Guide](https://vitejs.dev/guide/migration.html#general-changes) if you run into trouble.
+
+### Deprecated: Astro.canonicalURL
+
+You can now use the new [`Astro.url`](#astrourl) helper to construct your own canonical URL from the current page/request URL.
+
+```js
+// Before:
+const canonicalURL = Astro.canonicalURL;
+// After:
+const canonicalURL = new URL(Astro.url.pathname, Astro.site);
+```
+
 ## Astro 1.0 Beta
 
 On April 4, 2022 we released the Astro 1.0 Beta! 🎉

src/pages/en/reference/api-reference.md

@@ -91,13 +91,13 @@ const data = await Astro.glob<CustomDataFile>('../data/**/*.js');
 
 ### `Astro.request`
 
-`Astro.request` is a standard [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object. It can be used to get the `url`, `headers`, `method`, and even body of the request. Use `new URL(Astro.request.url)` to get a URL object.
+`Astro.request` is a standard [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object. It can be used to get the `url`, `headers`, `method`, and even body of the request. 
+
+See [`Astro.url`](#astrourl) for a full URL object of the current `Astro.request.url` value. This can be useful for accessing individual properties of the request URL, like pathname and origin.
 
 ```astro
----
-const url = new URL(Astro.request.url);
----
-<h1>Origin {url.origin}</h1>
+<h1>The current URL is: {Astro.request.url}</h1>
+<h1>The current URL pathname is: {Astro.url.pathname}</h1>
 ```
 
 ### `Astro.response`
@@ -123,16 +123,33 @@ Astro.response.headers.set('Set-Cookie', 'a=b; Path=/;');
 
 ### `Astro.canonicalURL`
 
-The [canonical URL][canonical] of the current page. If the `site` option is set, the site's origin will be the origin of this URL.
+:::caution[Deprecated]
+Use [`Astro.url`](#astrourl) to construct your own canonical URL. 
+:::
+
+The [canonical URL][canonical] of the current page.
 
-You can also use the `canonicalURL` to grab the current page's `pathname`.
+### `Astro.url`
+
+A full URL object of the current `Astro.request.url` value. Equivalent to `new URL(Astro.request.url)`. Useful for accessing individual properties of the request URL, like pathname and origin.
+
+```astro
+<h1>The current URL is: {Astro.url}</h1>
+<h1>The current URL pathname is: {Astro.url.pathname}</h1>
+<h1>The current URL origin is: {Astro.url.origin}</h1>
+```
+
+You can use `Astro.url` to create new URLs using the [`new URL()`](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) constructor. This is useful for creating canonical URLs, SEO meta tag URLs, links and more.
 
 ```astro
 ---
-const path = Astro.canonicalURL.pathname;
+// Example: Construct a canonical URL using your production domain
+const canonicalURL = new URL(Astro.url.pathname, Astro.site);
+// Example: Construct a URL for SEO meta tags
+const socialImageURL = new URL('/images/preview.png', Astro.url);
 ---
-
-<h1>Welcome to {path}</h1>
+<link rel="canonical" href={canonicalURL} />
+<meta property="og:image" content={socialImageURL} />
 ```
 
 ### `Astro.site`