Skip to main content
0 reactions

How to Use Path Aliases in TanStack Start

The Bookshop home page with the heading Welcome to the Bookshop, where Bookshop comes from a file imported with the #/ alias.
The heading reads siteName through the #/ alias.

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

JavaScript
import { name } from "#/path/to/file";
  • name is what the file exports.
  • #/ stands for the src folder.
  • path/to/file is the file’s path inside src, 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:

JavaScript
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:

JavaScript
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:

The Bookshop home page with the heading Welcome to the Bookshop, where Bookshop comes from a file imported with the #/ alias.
The heading reads siteName through the #/ alias.

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)):

JavaScript
"imports": {
  "#/*": "./src/*"
},

tsconfig.json maps it for TypeScript and your editor (TypeScript docs (opens in a new tab)):

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

vite.config.ts tells Vite to read those TypeScript paths (Vite docs (opens in a new tab)):

JavaScript
resolve: { tsconfigPaths: true },

The template also maps @/ in tsconfig.json. This series uses #/, which package.json maps too.

Common Mistakes

MistakeWhat happensDo this instead
Starting the path with #/src/#/ already means src, so the path points to src/srcStart 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

TanStack, React and other names mentioned are trademarks of their respective owners. JD Bots isn’t affiliated with or endorsed by TanStack.

0 comments