Tanstack Start Project Initialization (Node.js & Bun)

Hello! Welcome to the second module of our course.

In the first module, we established a strong foundation in Tanstack Router. We learned how to define routes, fetch data on the server with loaders, manage pending and error states, and, in our last lesson, implement type-safe validation for URL search parameters using Zod. You are now proficient in using Tanstack Router as a powerful routing and data-fetching library within a React application.

Today, we take the next major step. We move from using Tanstack Router as a library to adopting Tanstack Start, the full-stack framework built around it. This lesson directly addresses your goal of working with both Node.js and Bun environments. Our learning outcome is to initialize a Tanstack Start project using both Node.js and Bun runtimes.

This lesson will cover:

• The role of the Tanstack Start CLI in scaffolding a new project.
• Initializing a project in a standard Node.js environment.
• Exploring the key files and directories generated by the CLI.
• Repeating the process using the high-performance Bun runtime.
• Comparing the two setups and understanding the differences in tooling and configuration.

By the end of this lesson, you will have two identical starter projects running in two different server environments, ready for further development.

1. From Library to Framework: Tanstack Start

So far, we've used Tanstack Router to add server-side capabilities to a React project. Tanstack Start takes this further by providing a complete, opinionated framework structure. It's a meta-framework, similar in scope to Next.js or Remix, that uses Vite for its build tooling and provides a cohesive structure for building full-stack applications with server-side rendering, server functions, and more.

The primary way to begin is with the official command-line interface (CLI).

2. Initializing a Project with Node.js

Let's start with the most common JavaScript ecosystem: Node.js. The process is managed by a create-start-app package, which you can run with npm.

The following video provides an excellent walkthrough of this entire process, from running the CLI to exploring the generated project.

Step-by-Step with Node.js

Let's summarize the key steps shown in the video.

1. Run the CLI: In your terminal, execute the command. You'll be prompted for a project name and other options.

   npm create @tanstack/start@latest
   

   For the prompts, you can choose a project name (e.g., tanstack-start-node) and select Yes for Tailwind CSS and ESLint. We'll skip the other add-ons and examples for now to keep the base project clean.

2. Install Dependencies: Navigate into your new project directory and install the dependencies.

   cd tanstack-start-node
   npm install
   

3. Run the Development Server: Start the Vite development server.

   npm run dev
   

   You should now be able to open http://localhost:5173 (or a similar port) in your browser and see the default Tanstack Start homepage.

The project structure is mostly what you'd expect from a modern Vite + React setup, with one crucial addition related to SSR. Besides the src/routes directory we've already worked with, you'll find src/entry-client.tsx and src/entry-server.tsx. We will explore these files in detail in our next lesson, but for now, understand that they are the separate entry points for the code that runs in the browser versus the code that runs on the server.

3. Initializing a Project with Bun

Now, let's repeat the process using Bun. Bun is an all-in-one JavaScript toolkit that includes a runtime, package manager, and bundler. It's designed for speed, and you'll likely notice a significant difference in installation times.

The official Bun documentation provides a concise guide for using it with Tanstack Start.

Step-by-Step with Bun

Following the guide, the process is very similar, but with Bun-specific commands.

1. Run the CLI with Bun: Use bun create to scaffold the project. This command uses Bun to both fetch the create-start-app package and run it.

   bun create @tanstack/start@latest
   

   Again, choose a project name (e.g., tanstack-start-bun) and select the same options for Tailwind and ESLint. Notice how quickly Bun resolves and installs the initial dependencies.

2. Run the Development Server: Navigate into the new directory and start the dev server.

   cd tanstack-start-bun
   bun run dev
   

   The server will start, and you'll see the same application as before.

3. (Recommended) Update package.json: The Bun documentation recommends a small but important change to ensure Bun is used consistently. Open your package.json file and prefix the vite commands in the scripts section with bun --bun.

   Before:

   "scripts": {
     "dev": "vite",
     "build": "vite build",
     "serve": "vite preview"
   }
   

   After:

   "scripts": {
     "dev": "bun --bun vite",
     "build": "bun --bun vite build",
     "serve": "bun --bun vite preview"
   }
   

   This bun --bun flag ensures that the Vite process itself is executed by the Bun runtime, rather than defaulting to Node.js, which might be the system default. This guarantees that your development environment fully utilizes Bun's capabilities.

4. Comparing the Setups

You now have two identical applications running under two different JavaScript runtimes. The generated source code in the src folder is exactly the same. The difference lies entirely in the tooling and execution environment.

The key takeaway is that Tanstack Start is runtime-agnostic. Your application logic remains the same, and you can choose the runtime that best fits your project's performance requirements or your team's tooling preferences.

Conclusion

In this lesson, we successfully initialized our first Tanstack Start projects. We've seen how the official CLI scaffolds a complete application and how straightforward it is to use either the standard Node.js runtime or the modern, high-performance Bun runtime.

Key Takeaways:

• Tanstack Start is a full-stack framework that uses a CLI (create-start-app) for project scaffolding.
• You can initialize a project using npm create for a Node.js environment or bun create for a Bun environment.
• The generated application source code is identical regardless of the chosen runtime.
• When using Bun, it's best practice to update the package.json scripts to ensure Vite is executed by the Bun runtime.
• The project structure includes entry-client.tsx and entry-server.tsx, which are the distinct entry points for browser and server code.

We've laid the groundwork for our full-stack application. In our next lesson, we will dive into those new entry point files and explore a core concept of SSR frameworks: differentiating the server and client entry points and configuring environment variables for each context.