From 53c7ae8c666dc6783a0512b6f983979801955a97 Mon Sep 17 00:00:00 2001
From: Jonathan Neal <jonathantneal@hotmail.com>
Date: Tue, 14 Dec 2021 19:39:11 -0500
Subject: [PATCH] Update alias docs (#2204)

---
 docs/src/pages/guides/aliases.md | 67 +++++++++++++++++---------------
 1 file changed, 36 insertions(+), 31 deletions(-)

diff --git a/docs/src/pages/guides/aliases.md b/docs/src/pages/guides/aliases.md
index 2ba9137f61..4e3e0d5a49 100644
--- a/docs/src/pages/guides/aliases.md
+++ b/docs/src/pages/guides/aliases.md
@@ -1,46 +1,51 @@
 ---
 layout: ~/layouts/MainLayout.astro
 title: Aliases
-description: An intro to Snowpack aliases with Astro.
+description: An intro to aliases with Astro.
 ---
 
-An **alias** is a handy shortcut for your JavaScript imports. This can be a great option if you dislike long relative import paths with many repeating `../` segments. Define an alias to import things directly from some top-level project directory, no matter how deeply nested a file is located.
+An **alias** is a way to create shortcuts for your imports.
 
-With an alias, you can import from `"$components/SomeComponent.astro"` instead of `"../../../../../components/SomeComponent.astro"`.
+Aliases can help improve the development experience in codebases with many directories or relative imports.
 
-## Adding a custom alias
+```astro
+---
+// my-project/src/pages/about/company.astro
 
-To add a custom alias to your project, locate your project `snowpack.config.mjs` file. This configuration file contains the instructions and configuration for Astro's internal build tool [Snowpack](https://www.snowpack.dev/reference/configuration). If you don't see a `snowpack.config.mjs` file at the top-level of your project (inside the same folder as your `package.json`), you can create a blank file now.
-
-To add a new import alias, define a new `alias` entry:
-
-```js
-// snowpack.config.mjs
-export default {
-  alias: {
-    // Map "$components/*" imports to "src/components/*"
-    $components: './src/components',
-    // Map "$/*" imports to "src/*"
-    $: './src',
-    // Define your own!
-    '$my-special-alias': './src/some/special/folder',
-  },
-  // ...
-};
+import Button from '../../components/controls/Button.astro';
+import logoUrl from '../../assets/logo.png?url';
+---
 ```
 
-Once you have defined your alias(es) and restarted Astro (if needed) you can start importing from the alias anywhere in your project:
+In this example, a developer would need to understand the tree relationship between `src/pages/about/company.astro`, `src/components/controls/Button.astro`, and `src/assets/logo.png`. And then, if the `company.astro` file were to be moved, these imports would also need to be updated.
 
-```js
-import MyComponent from '$components/MyComponent.astro';
-import mySvgUrl from '$/logo.svg';
+You can add import aliases from either `tsconfig.json` or `jsconfig.json`.
+
+```json
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "asset:*": [
+        "src/assets/*?url"
+      ],
+      "component:*": [
+        "src/components/*.astro"
+      ]
+    }
+  }
+}
 ```
 
-You can read more about the `alias` configuration in [the Snowpack documentation.](https://www.snowpack.dev/reference/configuration#alias)
+With this change, you can now import using the aliases anywhere in your project:
 
-## Tips & Tricks
+```astro
+---
+// my-project/src/pages/about/company.astro
 
-- We recommend starting all aliases with the special `$` character. This is not required.
-- It is common to define a top-level `$` alias for your `src` directory. This is not required.
-- To add VSCode support for you aliases, you will also need to define your aliases in a `tsconfig.json` or `jsconfig.json` file via the `"paths"` config value. This will enable Intellisense in VSCode and most other text editors.
-- You don't need to use an alias with Astro! Some people prefer less magic in their code, and don't want to bother with extra steps for text editor support.
+import Button from 'component:Button';
+import logoUrl from 'asset:logo.png';
+---
+```
+
+These aliases are also integrated automatically into [VSCode](https://code.visualstudio.com/docs/languages/jsconfig) and other editors.