michael/astro
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

another pass on alias docs

Browse source
This commit is contained in:
Fred K. Schott 2021-08-06 15:22:35 -07:00
parent dfafbe54d7
commit 73020fab0c
1 changed files with 23 additions and 36 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

59
docs/src/pages/guides/aliases.md
View file

@ -3,56 +3,43 @@ layout: ~/layouts/MainLayout.astro
title: Aliases
---
An **alias** is a handy shortcut for your JavaScript import paths. This can be a great option if you dislike long relative import paths with many repeating `../` segments. Define an **alias** in your project to import directly from some directory no matter how deeply nested a file is located.
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.
With aliases, you can import from `"components/SomeComponent.astro"` instead of `"../../../../../components/SomeComponent.astro"`.
With an alias, you can import from `"$components/SomeComponent.astro"` instead of `"../../../../../components/SomeComponent.astro"`.
## Adding a custom alias
To add custom aliases to your project, located in the root of your project is the `snowpack.config.mjs` file. This configuration file contains the instructions for Astro's build tool [Snowpack](https://www.snowpack.dev/reference/configuration), on how to build out your Astro project.
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.
> **Note:** some projects don't come with this file out of the box, feel free to create it yourself. [More on snowpack.config.mjs.](https://www.snowpack.dev/reference/configuration)
Inside the file you will notice that there are already some predefined aliases.
To add a new import alias, define a new `alias` entry:
```ts
// snowpack.config.mjs
export default {
alias: {
components: './src/components',
'~': './src',
// Map "$components/*" imports to "src/components/*"
$components: './src/components',
// Map "$/*" imports to "src/*"
'$': './src',
// Define your own!
'$my-special-alias': './src/some/special/folder'
},
plugins: ['@snowpack/plugin-dotenv'],
workspaceRoot: '../',
// ...
};
```
To **add your own** alias just define it on a new line, like so:
```ts
// snowpack.config.mjs
export default {
alias: {
components: './src/components',
'~': './src',
'@public': './public', // This can be virtually anything
},
plugins: ['@snowpack/plugin-dotenv'],
workspaceRoot: '../',
};
```
| Key | Value |
| --------------------------- | ---------------------------------- |
| The keyword you'll be using | The path it will get replaced with |
## Usage
Now just use the **defined** aliases in a file of your choice:
Once you have defined your alias(es) and restarted Astro (if needed) you can start importing from the alias anywhere in your project:
```js
import '@public/assets/logo.svg';
import MyComponent from 'components/MyComponent/MyComponent.tsx';
import MyComponent from '$components/MyComponent.astro';
import mySvgUrl from '$/logo.svg';
```
You can read more about the `alias` configuration in [the Snowpack documentation.](https://www.snowpack.dev/reference/configuration#alias)
## Tips & Tricks
- 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.