TanStack Start + Convex Full-Stack Development

This skill provides expert guidance for working with a modern full-stack monorepo template built on TanStack Start, Convex, Three.js, and Nx. It enforces strict code conventions, proper testing practices, and efficient Convex backend patterns.

Project Architecture

The codebase is a Bun-powered Nx monorepo with:

`apps/web/` - TanStack Start React app with shadcn/ui and Three.js

`apps/convex/` - Convex real-time backend with Clerk auth

`packages/types/` - Shared TypeScript interfaces

`packages/utils/` - Shared utility functions

`.agent/` - AI assistant documentation and workspace learnings

**Tech Stack**: TanStack Start/Query/Router, Convex, Clerk, shadcn/ui, Tailwind CSS v4, Three.js, Framer Motion, Cloudflare Workers, Terraform

Critical First Steps

Before starting ANY work:

1. **Read `.agent/rules.md`** - Contains MANDATORY project-specific rules that OVERRIDE all default behavior

2. **Check `.agent/docs/*-learnings.md`** - Review workspace-specific insights and established patterns

3. **Use TodoWrite** - Track all multi-step tasks with the todo system

4. **Update learnings** - Document new insights in `.agent/docs/` after completing tasks

Code Conventions (STRICTLY ENFORCED)

File Naming

**ALWAYS use kebab-case** for all file names: `user-profile.tsx`, `search-utils.ts`

Test files: `[name].test.ts` or `[name].test.tsx`

**NO underscores, NO camelCase in file names**

Naming Conventions

**camelCase**: variables (`userName`), functions (`getUserData`), object properties

**PascalCase**: React components (`UserProfile`), classes, types/interfaces, enums

**UPPER_SNAKE_CASE**: constants (`MAX_RETRIES`), environment variables

UI Design Style

**Lowercase text throughout UI** - buttons, labels, headers all use lowercase

Example: "save changes" NOT "Save Changes", "user profile" NOT "User Profile"

Exception: Proper nouns and user-generated content

Code Style

**2-space indentation** for TypeScript/JavaScript/JSON

**No comments** unless explicitly requested

Use `// eslint-disable-next-line @typescript-eslint/no-unused-vars` for unused variables that can't be prefixed with underscore

Prefer existing utility functions over creating new ones

Import Rules

**Critical**: shadcn/ui components can ONLY be imported in `apps/web/` directory (only workspace with `components.json`). NEVER attempt shadcn imports elsewhere.

```typescript

// From web app

import { api } from '@template/convex';

import type { User } from '@template/types';

import { utilityFunction } from '@template/utils';

import { Button } from '@/components/ui/button'; // ONLY in apps/web/

// From backend

import { query, mutation } from './_generated/server';

import { v } from 'convex/values';

```

Development Workflow

Commands

```bash

bun run dev # Start full dev environment

bun run dev:frontend # Frontend only

bun run dev:backend # Backend only

bun run build # Build all projects

bun run test # Run all tests

bun run quality # Type check + lint + format check

bun run quality:fix # Fix quality issues

Nx commands

bun nx show projects # List projects

bun nx <task> <project> # Run task for specific project

bun nx run-many --target=<task> # Run task for all projects

```

Package Management

**Always use `bun`** - Never use npm, yarn, or npx

Use `bunx` for package execution

Add dependencies to appropriate workspace (root, app, or package)

Convex Backend Best Practices

Prefer Indexes Over Filters

```typescript

// GOOD - using index (fast)

const items = await ctx.db

.query('items')

.withIndex('by_user', (q) => q.eq('userId', userId))

.collect();

// AVOID - using filter (slow)

const items = await ctx.db

.query('items')

.filter((q) => q.eq(q.field('userId'), userId))

.collect();

```

Function Types

**Queries**: Read-only data fetching

**Mutations**: Data modifications

**Actions**: External API calls, can call mutations

**HTTP Actions**: REST endpoints

File Organization

Functions in `convex/` directory

API path: `convex/foo/bar.ts` → `api.foo.bar.functionName`

Schema in `convex/schema.ts`

Testing Guidelines

Frontend Tests

Use `@testing-library/react` for component testing

Include `/// <reference lib="dom" />` in test files

Use `screen` queries and Jest-DOM matchers

Clean up with `afterEach(cleanup)`

Backend Tests

Use `convex-test` for testing Convex functions

Initialize with `convexTest(schema, modules)`

Test mutations and queries with assertions

Verify data integrity after operations

General Rules

**No skipped tests** - they're considered failing

Use `describe` blocks for grouping

Test edge cases and error conditions

Quality Standards

Run `bun run quality` before submitting PRs to ensure:

**Type Safety**: Full TypeScript coverage

**Linting**: ESLint with TypeScript rules (don't fix linter errors unless requested)

**Testing**: Comprehensive test coverage

**Formatting**: Prettier with Tailwind plugin

Anti-Patterns to Avoid

Using npm/yarn/npx instead of bun/bunx

camelCase or snake_case in file names

Importing shadcn/ui outside `apps/web/`

Using filters instead of indexes in Convex queries

Skipping tests or leaving them disabled

Fixing linter errors unless explicitly requested

Adding comments unless requested

Introducing new patterns without permission

Starting work without checking `.agent/rules.md` and learnings

Implementation Checklist

When working on features:

1. Check `.agent/rules.md` for overriding rules

2. Review relevant `.agent/docs/*-learnings.md` files

3. Use TodoWrite to track multi-step tasks

4. Follow kebab-case file naming strictly

5. Use lowercase for all UI text

6. Import shadcn/ui only in `apps/web/`

7. Prefer Convex indexes over filters

8. Write tests for new functionality

9. Run `bun run quality` before completion

10. Update `.agent/docs/` with new learnings

TanStack Start + Convex Full-Stack Development

TanStack Start + Convex Full-Stack Development

Project Architecture

Critical First Steps

Code Conventions (STRICTLY ENFORCED)

File Naming

Naming Conventions

UI Design Style

Code Style

Import Rules

Development Workflow

Commands

Nx commands

Package Management

Convex Backend Best Practices

Prefer Indexes Over Filters

Function Types

File Organization

Testing Guidelines

Frontend Tests

Backend Tests

General Rules

Quality Standards

Anti-Patterns to Avoid

Implementation Checklist

Reviews (0)