A path alias is a short name for a folder. Instead of ../../lib/site, you import #/lib/site, which works the same from any file. A project created with the TanStack CLI already has the #/ alias for its src folder. This guide shows how to use it, and where it’s set up.
Syntax
import { name } from "#/path/to/file";
nameis what the file exports.#/stands for thesrcfolder.path/to/fileis the file’s path insidesrc, without its extension.
TanStack Start’s Path Aliases (opens in a new tab) guide covers aliases in general.
Prerequisites
- A TanStack Start app created with the TanStack CLI, such as the Bookshop from Part 2.
Step 1: Create a File to Import
Create src/lib/site.ts with one value in it, the site’s name:
export const siteName = "Bookshop";
Step 2: Import It with the Alias
In src/routes/index.tsx, import siteName with the alias, and use it in the heading. In JSX, curly braces show the value of a variable:
import { createFileRoute } from "@tanstack/react-router";
import { siteName } from "#/lib/site";
export const Route = createFileRoute("/")({ component: Home });
function Home() {
return (
<main className="mx-auto max-w-2xl p-8">
<h1 className="text-4xl font-bold">Welcome to the {siteName}</h1>
<p className="mt-4 text-lg">Find your next favourite book.</p>
<h2 className="mt-8 text-2xl font-semibold">Featured books</h2>
<ul className="mt-2 list-disc pl-6 text-lg">
<li>The Paper Lantern Café</li>
<li>Salt and Starlight</li>
</ul>
</main>
);
}
Without the alias, the same import from src/routes/index.tsx would be "../lib/site".
Step 3: Check the Page
Start the dev server with npm run dev and open http://localhost:3000. The heading now gets its name from src/lib/site.ts:

Where the Alias Is Set Up
The CLI sets up #/ in three places, and each tool reads its own:
package.json maps it for Node.js. Node.js calls this “subpath imports”, and their names must start with # (Node.js docs (opens in a new tab)):
"imports": {
"#/*": "./src/*"
},
tsconfig.json maps it for TypeScript and your editor (TypeScript docs (opens in a new tab)):
"paths": {
"#/*": ["./src/*"],
"@/*": ["./src/*"]
},
vite.config.ts tells Vite to read those TypeScript paths (Vite docs (opens in a new tab)):
resolve: { tsconfigPaths: true },
The template also maps @/ in tsconfig.json. This series uses #/, which package.json maps too.
Common Mistakes
| Mistake | What happens | Do this instead |
|---|---|---|
Starting the path with #/src/ | #/ already means src, so the path points to src/src | Start right after src: #/lib/site |
FAQ
Can I add my own alias? Yes. Add it to paths in tsconfig.json; Vite reads it because of tsconfigPaths: true. TanStack Start’s Path Aliases guide shows an example with ~/.
Conclusion
In a TanStack Start app from the CLI, #/ points to src, so import { siteName } from "#/lib/site" works from any file. It’s set up in package.json, tsconfig.json and vite.config.ts.
Additional Resources
- Path Aliases (opens in a new tab) in the TanStack Start docs
- Subpath imports (opens in a new tab) in the Node.js docs
- paths (opens in a new tab) in the TypeScript docs
Related
- TanStack Start Tutorial — Part 2: Create Your First TanStack Start App
- TanStack Start Tutorial for Beginners, every part of the series
TanStack, React and other names mentioned are trademarks of their respective owners. JD Bots isn’t affiliated with or endorsed by TanStack.
0 comments