Getting Started with TSStarter

Welcome to TSStarter! This guide will help you get up and running with your new full-stack TypeScript application in just a few minutes.

Prerequisites

Before you begin, make sure you have the following installed:

• Node.js (v20 or higher)
• Bun (recommended package manager)
• Git

Installing Bun

If you don't have Bun installed, you can install it with:

curl -fsSL https://bun.sh/install | bash

## Quick Start

### 1. Access Your Repository

After purchasing TSStarter, you'll receive a GitHub invitation email. Accept the invitation to access your private repository.

```bash
git clone https://github.com/tsstarter/tsstarter your-project-name
cd your-project-name

2. Install Dependencies

bun install

3. Set Up Environment Variables

Copy the example environment file and configure it:

cp env.example .env

Edit .env and configure the following variables:

Required Variables

# Required - Generate a secure random string (32+ characters)
BETTER_AUTH_SECRET=your-secret-key-here

# Database - Use SQLite for local development
DATABASE_URL=file:./local.db

# Development
BASE_URL=http://localhost:3000
VITE_BASE_URL=http://localhost:3000

Authentication Configuration (Choose One or More)

TSStarter supports multiple authentication methods. Choose the ones that work best for your setup:

Option 1: Email/Password Authentication

# Email Service (Required for email verification)
PLUNK_API_KEY=your-plunk-api-key

Option 2: OAuth Providers (GitHub & Google)

# GitHub OAuth
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

# Google OAuth
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

Option 3: No Authentication (Development Only)

# Leave authentication variables empty for development
# Users can still access the app without authentication

### 4. Configure Local Database

For local development, the database is already configured to use SQLite. The `drizzle.config.ts` file should look like this:

```typescript
import { config } from "dotenv";
import { defineConfig } from "drizzle-kit";

config({ path: ".env" });

export default defineConfig({
  schema: "./src/db/schema.ts",
  out: "./drizzle/migrations",
  dialect: "sqlite",
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
  verbose: true,
  strict: true,
});

5. Set Up the Database

Generate and run the database migrations:

# Generate migration files
bun run db:generate

# Push schema to database
bun run db:push

6. Start the Development Server

bun run dev

Your application will be available at http://localhost:3000.

Optional Configuration

Note: These features are optional and can be configured later. You can get started without them.

AI Integration

For AI chat functionality, add your API keys:

# AI Providers
OPENAI_API_KEY=your-openai-api-key
ANTHROPIC_API_KEY=your-anthropic-api-key

Advanced Configuration (Optional)

Payment Integration (Polar)

Note: This is only needed if you want to implement payment processing. You can skip this for initial setup.

For payment processing:

# Polar Payments
VITE_POLAR_PUBLIC_CHECKOUT_URL=https://sandbox.polar.sh/checkout/your-checkout-link
VITE_POLAR_SUCCESS_URL=http://localhost:3000/payment/success
POLAR_WEBHOOK_SECRET=your-polar-webhook-secret

Available Scripts

Project Structure

tsstarter/
├── 📁 src/
│   ├── 🧩 components/           # React components
│   │   ├── ui/                 # Reusable UI components (shadcn/ui)
│   │   └── app/                # Application-specific components
│   ├── 🗄️ db/                  # Database layer
│   │   ├── schema.ts           # Drizzle schema definitions
│   │   └── migrate.ts          # Database migrations
│   ├── 🔧 lib/                 # Shared utilities
│   │   ├── auth/               # Authentication logic
│   │   ├── hooks/              # Custom React hooks
│   │   ├── orpc.ts             # oRPC client configuration
│   │   └── utils.ts            # Helper functions
│   ├── 🛣️ routes/              # Application routes
│   │   ├── _authed/            # Protected routes
│   │   ├── api/                # API endpoints
│   │   └── __root.tsx          # Root layout
│   ├── 🖥️ server/              # Server-side code
│   │   ├── routes/             # oRPC procedures
│   │   ├── handler.ts          # Request handler
│   │   └── orpc.ts             # oRPC server setup
│   └── 🎨 styles.css           # Global styles
├── 📁 content/                 # MDX content
│   ├── blog/                   # Blog posts
│   └── docs/                   # Documentation
├── 📁 drizzle/                 # Database migrations
├── 📁 public/                  # Static assets
└── 📄 Configuration files

Development Workflow

1. Local Development

bun run dev

• Hot reload enabled
• Type checking in real-time
• Error overlay with detailed messages

2. Database Management

# View database in browser
bun run db:studio

# Generate new migrations
bun run db:generate

# Apply migrations
bun run db:push

3. Testing

# Run tests
bun run test

# Type checking
bun run check-types

# Linting
bun run lint

Next Steps

1. Explore the Dashboard - Check out the task management and analytics
2. Test Real-time Features - Try the live task updates and notifications
3. Customize the UI - Modify components in src/components/ui/
4. Add Your Content - Update blog posts in content/blog/
5. Configure Authentication - Set up your OAuth providers
6. Deploy - Deploy to Vercel, Railway, or your preferred platform

Troubleshooting

Common Issues

Port already in use:

# Kill processes on ports 3000, 3001, 3002
lsof -ti:3000,3001,3002 | xargs kill -9

Database connection issues:

# Reset database
rm local.db
bun run db:push

Dependencies issues:

# Clear cache and reinstall
rm -rf node_modules bun.lockb
bun install

Getting Help

• 📚 Check the documentation for detailed guides
• 💬 Contact support at tsstarter@icloud.com

Happy coding! 🚀