TanStack Start Starter

A minimal starter template for TanStack Start — the full-stack React framework powered by TanStack Router.

Tech Stack

This starter leverages cutting-edge tools with a minimal configuration:

Category	Technology	Version
Framework	TanStack Start	Latest
Styling	Tailwind CSS	4
Language	TypeScript Native	7 Preview
Build Tool	Vite	8 Beta
Linter	oxlint	Latest
Formatter	oxfmt	Latest
Git Hooks	Lefthook	Latest
Utility	@lightsound/cn	Latest
Runtime	Bun	Latest

Getting Started

Prerequisites

• Bun installed on your machine

Installation

# Clone the repository
git clone https://github.com/lightsound/tanstack-start-start.git
cd tanstack-start-start

# Install dependencies (git hooks are automatically set up)
bun install

# Start development server
bun run dev

Scripts

Command	Description
bun run dev	Start development server
bun run build	Build for production
bun run start	Preview production build
bun run oxc:check	Run linter and formatter check
bun run oxc:fix	Auto-fix lint issues and format code
bun run oxlint:check	Run oxlint
bun run oxlint:fix	Run oxlint with safe fixes
bun run oxfmt:check	Check formatting without writing
bun run oxfmt:fix	Format files in place

VS Code Configuration

Recommended Extension

This project recommends installing the oxc extension for the best development experience.

Editor Settings

The included .vscode/settings.json provides the following configurations:

• Format on Save: oxfmt automatically formats your code when you save a file
• Read-only Files: The following files are set to read-only to prevent accidental edits:
  • **/*.md — Markdown files should be managed by AI, not edited directly
  • bun.lock — Auto-generated lockfile, should not be manually modified
  • **/routeTree.gen.ts — Auto-generated by TanStack Router, should not be manually modified

About oxlint Configuration

This starter keeps the rule categories minimal with only the correctness category enabled, while still enabling practical plugins and type-aware checks. This catches obvious bugs without turning the baseline ruleset into a noisy default.

The current oxlint.config.ts also enables:

• react, react-perf, import, jsx-a11y, promise plugins
• typeAware, typeCheck, and denyWarnings
• a no-default-export rule with config-file/router overrides

You can make the linting stricter by adding more categories to oxlint.config.ts:

import { defineConfig } from "oxlint";

export default defineConfig({
  categories: {
    correctness: "error",
    suspicious: "warn",
    perf: "warn",
  },
});

Available categories: correctness, suspicious, perf, style, pedantic, restriction, nursery

About oxfmt Configuration

This starter uses oxfmt with the following features enabled in oxfmt.config.ts:

• Import Sorting: Automatically sorts and organizes import statements
• Tailwind CSS Class Sorting: Keeps utility classes in a consistent order
• package.json Sorting: Sorts keys and scripts in package.json

About @lightsound/cn

@lightsound/cn is the most lightweight className utility — smaller than both classnames and clsx. It provides the same conditional class joining API with a minimal footprint.

This starter also includes tailwind-merge as a peer dependency, so you can switch to Tailwind Merge–aware cn by simply changing the import path:

// Basic usage (ultra-lightweight, no Tailwind Merge)
import { cn } from "@lightsound/cn";

// With Tailwind Merge (resolves conflicting Tailwind classes)
import { cn } from "@lightsound/cn/tw-merge";

For example, with the tw-merge import, conflicting classes are resolved automatically:

cn("text-red-500", isBlue && "text-blue-500");
// isBlue=true  → "text-blue-500" (conflict resolved by tailwind-merge)
// isBlue=false → "text-red-500"

Git Hooks with Lefthook

This starter uses Lefthook for managing git hooks:

• pre-commit: Runs linting and formatting on staged files (fast)
• pre-push: Runs the full oxc:check script before pushing (complete)

Git hooks are automatically installed when you run bun install.

Developer Tools

In development mode, this starter includes TanStack Router DevTools for debugging routes and navigation. The DevTools panel appears in the bottom-right corner of your application.

License

This project is licensed under the MIT License - see the LICENSE file for details.