alias

Without configuration, Meeko defines four path aliases: ~/ (the project root), @/ (app/), #shared/ (shared/) and #server/ (server/, only in server code). alias adds your own or changes these: each key is a prefix ending in / and each value is a project folder or false to remove the alias.

An alias inherits the scope of its target folder, like auto-imports: an alias pointing to server/ only exists in server code.

Usage#

// meeko.config.ts
import { defineMeekoConfig } from "@meekojs/meeko/framework";

export default defineMeekoConfig({
  alias: {
    "ui/": "app/components/ui/",
    "db/": "server/db/",
    "#server/": false,
  },
});

// a .ts file in app/
import { Button } from "ui/Button";

Type#

readonly alias?: Readonly<Record<string, string | false>>

Options#

• Key. Ends in /; no spaces, * or \; does not start with . or /; no //.
• Value. A relative path inside the project, or false. A nonexistent folder is not an error: the import fails at resolution time.

Result#

It applies in Vite (meeko dev, meeko build and all adapters), the tsconfig files Meeko generates (used by meeko check and the editor), the language server and @utilities modules. A custom alias points exactly to its folder; it does not search layers like Meeko's aliases. Changing a Meeko alias ("@/": "src/") makes it a custom alias, with the scope of its new folder.

Examples#

A design folder#

import { defineMeekoConfig } from "@meekojs/meeko/framework";

export default defineMeekoConfig({ alias: { "ui/": "app/components/ui/" } });

<script lang="ts">
import * as Dialog from "ui/Dialog.meeko";
</script>

Free #shared/ for Node subpath imports#

import { defineMeekoConfig } from "@meekojs/meeko/framework";

// package.json declares "imports": { "#shared/*": "./lib/shared/*.js" }
export default defineMeekoConfig({ alias: { "#shared/": false } });

Without this, Meeko detects the conflict, yields the prefix to package.json and warns once per process.

A project with src/#

import { defineMeekoConfig } from "@meekojs/meeko/framework";

export default defineMeekoConfig({ alias: { "@/": "src/" } });

If tsconfig.json already had "@/*": ["./src/*"], declare it here too: Vite does not read TypeScript paths.

Common mistakes#

A key without a trailing /#

export default defineMeekoConfig({ alias: { "@ui": "app/components/ui/" } });

meeko dev, meeko build, meeko check and meeko routes stop with …/meeko.config.ts: alias "@ui" debe ser un prefijo que termine en / (como "@/", "~/" o "lib/"), sin espacios, * ni \, y que no empiece por . ni /.

import { defineMeekoConfig } from "@meekojs/meeko/framework";
export default defineMeekoConfig({ alias: { "@ui/": "app/components/ui/" } });

A folder outside the project#

export default defineMeekoConfig({ alias: { "ui/": "../design-system/src/" } });

…/meeko.config.ts: alias "ui/" debe ser una ruta relativa dentro del proyecto (su carpeta o la de un layer): ../design-system/src/. For code from another repository, install it as a package.

import { defineMeekoConfig } from "@meekojs/meeko/framework";
export default defineMeekoConfig({ alias: { "ui/": "layers/design/app/components/" } });

A server alias in a component#

<script lang="ts">
import { db } from "db/client"; // "db/": "server/db/"
</script>

meeko check, the editor and the browser build report MEEK108, even with import type. For a server type, use ~/server/….

<script server lang="ts">
import { db } from "db/client";
export const total = await db.orders.count();
</script>

Notes#

• meeko.config.ts. Node loads the configuration without Vite: neither it nor its imported modules can use aliases.
• Editor. In an untrusted workspace, the editor reads alias without executing the configuration only if it is an object literal containing strings and false; otherwise, it uses the default aliases.
• Priority. A paths pattern in tsconfig.json or a Vite resolve.alias covering a Meeko prefix disables it, with a warning; a #… entry in package.json imports also wins.
• Packages. Modules in node_modules never receive project aliases.

Related#

• importsAuto-import folders in addition to the defaults, each with the scope of its containing folder, app, shared or server.
• layersProject folders that contribute pages, components, auto-imports, layouts and plugins to the application, in the listed order.
• Path aliasesMeeko as a full-stack framework
• Custom aliases: aliasMeeko as a full-stack framework
• Alias scopesMeeko as a full-stack framework
• Alias priority and conflictsMeeko as a full-stack framework