Conventions in the Tanstack Start Supabase Turbo Starter Kit

Below are some of the conventions used in the Tanstack Start Supabase Turbo Starter Kit.

You're not required to follow these conventions: they're simply a standard set of practices used in the core kit. If you like them - I encourage you to keep these during your usage of the kit - so to have consistent code style that you and your teammates understand.

Turborepo Packages

In this project, we use Turborepo packages to define reusable code that can be shared across multiple applications.

• Apps are used to define the main application, including routing, layout, and global styles.
• Apps pass down configuration to the packages, and the packages provide the corresponding logic and components.

Creating Packages

Should you create a package for your app code?

• Recommendation: Do not create a package for your app code unless you plan to reuse it across multiple applications or are experienced in writing library code.
• If your application is not intended for reuse, keep all code in the app folder. This approach saves time and reduces complexity, both of which are beneficial for fast shipping.
• Experienced developers: If you have the experience, feel free to create packages as needed.

Imports and Paths

When importing modules from packages or apps, use the following conventions:

• From a package: Use @kit/package-name (e.g., @kit/ui, @kit/shared, etc.).
• From an app: Use #/ (mapped to apps/web/src, e.g., #/components, #/lib, #/config, etc.).

Route File Conventions

Routes live in apps/web/src/routes/ and follow TanStack Router file-based routing:

• A folder (or file) prefixed with an underscore (e.g., _marketing, _user) is a pathless layout route — it groups children under a shared layout without adding a URL segment.
• A $-prefixed segment (e.g., $account) is a dynamic segment.
• route.tsx defines the layout for a folder; index.tsx defines its index page.
• Non-route code (shared components, utilities, config) lives outside routes/ — in #/components, #/lib, and #/config.

Server Code

Server-only modules use the .server.ts filename suffix (e.g., server-client.server.ts), and shared server logic for the app lives in apps/web/src/lib/server.

• This convention makes it clear where the code is meant to run, which matters in Tanstack Start where the client/server distinction can be blurry.
• The .server.ts suffix ensures these modules are never bundled into client-side code.
• Server functions are defined with createServerFn in *.functions.ts files.