← Back to Blog

Why the alias is relative

·5 min read

Every alias pyrpc injects points at "./__pyrpc.ts", a path that starts with a dot. That dot is doing real work, and its absence would be a quiet correctness bug waiting to happen.

What the dot means

A leading ./ makes the target a relative path: resolved against the config file's directory. The generated __pyrpc.ts lives in the client directory, the same directory that holds vite.config.ts and next.config.*. The dot pins the alias to that guaranteed relationship.

What happens without it

Drop the dot and you get "@pyrpc/types": "__pyrpc.ts". Now the semantics change: an extensionless, non-dotted string in an alias is treated as a package-style specifier. Vite and Turbopack would attempt to resolve it like a bare import (walking up node_modules looking for a package called __pyrpc.ts. That package does not exist, so the alias silently fails to match and the resolution falls through to the real placeholder. The symptom would be identical to no alias at all) the throwing Proxy (but the error message would point you in the wrong direction.

Relative vs absolute

An absolute path (/home/you/project/__pyrpc.ts) would also resolve, but it would be wrong in a subtler way. The generated file is a build artifact tied to the client directory. An absolute path hardcodes a machine-specific location into a file that typically gets committed, so it breaks every other developer's checkout and every CI machine. The relative form is portable: it survives moving the repo, cloning to a new path, and running in Docker.

The tsconfig side does the same

The tsconfig paths alias mirrors the choice: "./__pyrpc.ts", resolved relative to the tsconfig's directory, which is also the client directory. Both layers agree on the same relative target, so the compiler and the bundler converge on the same file without any absolute coordinates.

The rule of thumb

When an alias targets a file that is a sibling of the config doing the aliasing, express it relative to that config. It is the only form that is simultaneously correct for resolution, portable across machines, and robust to repo moves. The leading dot is not style, it is the difference between "a sibling file" and "a package that was never published".