Clean Imports in Astro with Path Aliases

When working on an Astro project, you quickly realize that importing files can get messy. Nobody enjoys writing imports like this:

import Header from "../../../components/Header.astro";
import MainLayout from "../../layouts/MainLayout.astro";

It’s not only hard to read, but also painful to maintain when the project grows. Luckily, Astro (thanks to TypeScript’s config system) allows us to define path aliases – short and meaningful prefixes for your imports.

Why use path aliases?

• Cleaner imports → no more ../../../
• More readable code → you instantly know where a file comes from
• Easier refactoring → if you move a folder, you don’t need to fix hundreds of import paths
• Consistency → everyone on the team imports files the same way

Setting up aliases in Astro

Astro uses TypeScript (or JavaScript) config files to define path aliases. All you need to do is add a tsconfig.json or jsconfig.json at the root of your project and configure the paths option.

Here’s an example:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@c/*": ["src/components/*"],
      "@l/*": ["src/layouts/*"],
      "@s/*": ["src/style/*"],
      "@img/*": ["src/assets/img/*"],
      "@data/*": ["src/data/*"]
    }
  }
}

What do these aliases mean?

• @/* → everything inside the src/ folder
• @c/* → components (src/components/)
• @l/* → layouts (src/layouts/)
• @s/* → styles (src/style/)
• @img/* → images and static assets (src/assets/img/)
• @data/* → data files (src/data/)

You can, of course, adjust these to match your project’s structure.

Using aliases in your code

Instead of writing:

import Header from "../../../components/Header.astro";
import MainLayout from "../../layouts/MainLayout.astro";

You can now simply write:

import Header from "@c/Header.astro";
import MainLayout from "@l/MainLayout.astro";

Much cleaner, right? ✨

Tips & gotchas

• Restart the dev server after changing tsconfig.json
• If you’re using VS Code, it will automatically understand these paths
• Aliases work in both .astro and .ts/.js files

Final thoughts

Path aliases are a small setup step that can make a big difference in how you write and maintain your Astro codebase. Cleaner imports mean less frustration and more focus on building your website.

If you’re starting a new Astro project today, I highly recommend setting up aliases right away – your future self will thank you! 🚀