Aliases and tsconfig paths

Path patterns like **/hooks/** are only useful if apotheke can tell that @/hooks/use-user and ../../hooks/use-user are the same folder. It can, because it resolves aliases before matching.

tsconfig is read automatically

On startup apotheke looks for tsconfig.json next to your config file and pulls in compilerOptions.paths and compilerOptions.baseUrl. Given:

{
    "compilerOptions": {
        "baseUrl": ".",
        "paths": {
            "@/*": ["./src/*"],
            "~/lib/*": ["./src/lib/*"]
        }
    }
}

both @/hooks/use-user and ~/lib/format resolve to real paths under src/, and a **/hooks/** pattern matches the first one. You usually do not need to configure anything.

Declaring aliases manually

Set aliases when there is no tsconfig, or when your bundler defines aliases TypeScript does not know about:

export default {
    aliases: {
        '@': './src',
        '#internal': './packages/internal/src'
    },
    groups: [{ name: 'Hooks', match: ['**/hooks/**'] }]
};

Keys are written without the trailing /* — '@', not '@/*'.

Precedence

Aliases you write by hand win. When the same key exists in both places, the value from apotheke.config.mjs is kept and the tsconfig entry is ignored, so you can override a path mapping without editing tsconfig.

baseUrl behaves the same way: a value in your config takes precedence over the one in tsconfig.

Multiple targets

TypeScript allows an array of fallback locations per alias:

{ "paths": { "@/*": ["./src/*", "./generated/*"] } }

apotheke uses the first entry only. If grouping depends on the second location, declare that alias explicitly in aliases.