[FR] Add TanStack Start app example

[laakal]

Hi @nktnet1

Amazing work on this project—thank you!

I’d love to see an example app showcasing TanStack Start. A simple but complete example would be incredibly helpful for learning, onboarding, and demonstrating best practices.

[nktnet1]

@laakal have you seen some of these projects?

• https://github.com/AmanVarshney01/create-better-t-stack
• https://github.com/BearStudio/start-ui-web
• https://github.com/sunshineLixun/ShipFullStack

These may already satisfy your use case for Tanstack Start. If I do decide to add it, it'll be an extension branch similar to the NextJS-Fumadocs one (bottom of the README.md).

Will convert this to a discussion :).

[laakal]

@nktnet1 thanks for the pointers. I’ve already been using create-better-t-stack as a reference/interpretation for how TanStack Start projects are commonly structured.

One thing I noticed, though: your repo seems to prefer “Build packages first” (build packages in dev mode), whereas create-better-t-stack leans toward consuming source directly.

Could you share the reasoning behind choosing “build packages first” here?

[nktnet1]

Hey @laakal,

It's mainly to do with turborepo caching and typescript performance. It's negligible in most cases though if your project is small, so I think using just-in-time-packages like what you're doing is fine and you don't need to follow my example.

You can read up on this here:

• https://turborepo.com/docs/core-concepts/internal-packages#just-in-time-packages

I've also copied the documentation here in case the page is removed in the future:

Click to view

 

Internal Packages are libraries whose source code is inside your Workspace. You can quickly make Internal Packages to share code within your monorepo and choose to publish them to the npm registry if you need to later.

Internal Packages are used in your repository by installing them in package.json similar to an external package coming from the npm registry. However, instead of marking a version to install, you can reference the package using your package manager's workspace installation syntax.

pnpm

{
  "dependencies": {
    "@repo/ui": "workspace:*"
  }
}

yarn

{
  "dependencies": {
    "@repo/ui": "*"
  }
}

npm

{
  "dependencies": {
    "@repo/ui": "*"
  }
}

bun

{
  "dependencies": {
    "@repo/ui": "workspace:*"
  }
}

In the Creating an Internal Package guide, you can build an Internal Package from the beginning using the Compiled Package strategy. This page describes other strategies for creating Internal Packages and their tradeoffs, including publishing the package to the npm registry to create an External Package.

You can then import the package into your code like an external package:

import { Button } from '@repo/ui';

export default function Page() {
  return <Button>Submit</Button>;
}

Compilation Strategies

Depending on what you need from your library, you can choose one of three compilation strategies:

• Just-in-Time Packages: Allow application bundlers to compile the package as it is used.
• Compiled Packages: Compile the package using a build tool like tsc or a bundler.
• Publishable Packages: Compile and prepare a package for publishing to the npm registry.

Just-in-Time Packages

A Just-in-Time package is compiled by the application that uses it. You can use TypeScript or uncompiled JavaScript directly, with minimal configuration.

This strategy is useful when:

• Applications use modern bundlers like Turbopack, webpack, or Vite.
• You want minimal setup.
• You accept slower builds when cache is missed.

Example package.json:

{
  "name": "@repo/ui",
  "exports": {
    "./button": "./src/button.tsx",
    "./card": "./src/card.tsx"
  },
  "scripts": {
    "lint": "eslint . --max-warnings 0",
    "check-types": "tsc --noEmit"
  }
}

Key points:

• TypeScript is exported directly.
• No build script is required.

Limitations and tradeoffs

• Consumers must handle transpilation.
• TypeScript compilerOptions.paths cannot be used.
• Turborepo cannot cache builds.
• Type errors in dependencies surface in consumers.

Compiled Packages

A Compiled Package handles its own compilation using a tool like tsc.

Example package.json:

{
  "name": "@repo/ui",
  "exports": {
    "./button": {
      "types": "./src/button.tsx",
      "default": "./dist/button.js"
    },
    "./card": {
      "types": "./src/card.tsx",
      "default": "./dist/card.js"
    }
  },
  "scripts": {
    "build": "tsc"
  }
}

Compiled outputs are written to a directory like dist and can be cached by Turborepo.

Limitations and tradeoffs

• Most packages should use tsc.
• Bundlers should only be used for special cases.
• Requires more configuration and deeper TypeScript knowledge.

Publishable Packages

Publishable Packages must work for unknown consumers and require strict configuration.

Publishing typically involves:

• Versioning
• Changelogs
• Registry authentication

The recommended tool for this process is changesets.

For full details, see the Publishing packages guide.