Path Aliases & Real File Paths

Lumio Theme Documentation

Lumio uses import aliases heavily, and that can be confusing because the imports often do not match the real directory names.

For example, you will see imports like:

import HomeBanner from "@/components/sections/HomeBanner.astro";

But there is no src/components/ directory.

The Actual Alias Mapping

The aliases are defined in tsconfig.json:

"paths": {
  "@/components/*": ["./src/layouts/components/*"],
  "@/shortcodes/*": ["./src/layouts/shortcodes/*"],
  "@/helpers/*": ["./src/layouts/helpers/*"],
  "@/*": ["./src/*"]
}

What That Means

@/components/... really means src/layouts/components/...
@/shortcodes/... really means src/layouts/shortcodes/...
@/helpers/... really means src/layouts/helpers/...

Common Examples

This import:

import Logo from "@/components/global/Logo.astro";

Actually points to:

src/layouts/components/global/Logo.astro

This import:

import Accordion from "@/shortcodes/Accordion.astro";

Actually points to:

src/layouts/shortcodes/Accordion.astro

Why This Matters

When a doc or code comment tells you to edit @/components/..., you need to know the real file lives under src/layouts/components/....

Without that mapping, users often think files are missing or duplicated.

page shells: src/layouts/Base.astro
reusable sections: src/layouts/components/sections/
widgets: src/layouts/components/widgets/
global UI: src/layouts/components/global/
MDX shortcodes: src/layouts/shortcodes/

Once you understand the alias layer, the project becomes much easier to navigate.