TinyShip
TinyShip
TinyShip
TinyShip
TinyShip Documentation
TinyShip User GuideGetting StartedBasic Configuration
Credits System Configuration
Storage Service ConfigurationDatabase ConfigurationCaptcha Configuration
Development Best PracticesLocal E2E Workflow
User Guide

Getting Started

Set up and run TinyShip project in your local environment

This guide will help you set up and run the TinyShip project in your local environment.

System Requirements

Before starting, ensure your development environment meets the following requirements:

  • Node.js: >= 22.20.0 (Must use 22.20.0 or higher LTS version)
  • PNPM: >= 9.0.0 (Recommended package manager)
  • SQLite / PostgreSQL: choose one (PostgreSQL is the default recommendation; choose SQLite/D1 only if you explicitly plan to use Cloudflare D1)

Due to oxc-parser native binding issues with Nuxt 4, Node.js version must be >= 22.20.0. Lower versions may cause installation failures.

Quick Installation

Clone the Project

git clone https://github.com/TinyshipCN/tinyship.git
cd tinyship

# Or use SSH
git clone git@github.com:TinyshipCN/tinyship.git
cd tinyship

Install AI Agent Skills (Optional, Recommended)

If you use an AI editor (Cursor, Claude Code, Codex, OpenCode, etc.), you can install TinyShip Agent Skills for an AI-guided setup experience:

npx skills add TinyshipCN/tinyship-skills

After installation, just tell your AI "help me set up TinyShip", "all-in Cloudflare", "configure Stripe payment", etc. The AI will interactively guide you through the configuration. Supports 67+ AI editors.

Install PNPM (if not installed)

# Install pnpm using npm
npm install -g pnpm

# Or use corepack (Node.js 16.10+)
corepack enable
corepack prepare pnpm@latest --activate

# Verify installation
pnpm --version

Copy Environment Variables Template

cp env.example .env

Install Project Dependencies

pnpm install

Database Configuration

TinyShip defaults to PostgreSQL (pg) as the most stable and fully validated option.\nIt also supports sqlite (local file) and d1 (Cloudflare D1) for supplemental scenarios.

1. PostgreSQL (default, recommended, most stable)

Method 1: Using Docker (Recommended)

docker run --name tinyship-db \
  -e POSTGRES_USER=tinyship \
  -e POSTGRES_PASSWORD=your_password \
  -e POSTGRES_DB=tinyship \
  -p 5432:5432 \
  -d postgres:15

# Verify container is running
docker ps | grep tinyship-db

Method 2: Local Installation

sudo -u postgres createuser --interactive tinyship
sudo -u postgres createdb tinyship --owner=tinyship
sudo -u postgres psql -c "ALTER USER tinyship PASSWORD 'your_password';"

Method 3: Cloud Database Service

Supported cloud providers:

  • Vercel Postgres: Seamless integration with Vercel deployment
  • Supabase: Free tier available, easy setup
  • AWS RDS: Enterprise-grade option

Configure database connection in project root .env:

# DB_DIALECT defaults to pg
DB_DIALECT="pg"
DATABASE_URL="postgresql://username:password@localhost:5432/tinyship"

# Optional: SQLite (D1-compatible)
# DB_DIALECT="sqlite"
# SQLITE_DB_PATH="./data/local.sqlite"
pnpm db:check
pnpm db:push
pnpm db:seed

2. SQLite (optional, D1-compatible)

DB_DIALECT="sqlite"
# SQLITE_DB_PATH="./data/local.sqlite"
pnpm db:check:sqlite
pnpm db:push:sqlite
pnpm db:seed:sqlite
pnpm db:studio:sqlite

3. D1 and SQLite relationship

  • sqlite: local file database
  • d1: Cloudflare Workers hosted SQLite
  • both reuse the same schema
  • for Cloudflare Workers deploy, use DB_DIALECT="d1"

This creates two test users:

  • Admin: admin@example.com / admin123 (role: admin)
  • User: user@example.com / user123456 (role: user)

Minimal Auth Configuration

Configure authentication environment variables in .env:

.env
BETTER_AUTH_SECRET="your-secret-key-here-32-characters-min"
BETTER_AUTH_URL="http://localhost:7001"
DB_DIALECT="pg"
DATABASE_URL="postgresql://username:password@localhost:5432/tinyship"

# Optional: SQLite (D1-compatible)
# DB_DIALECT="sqlite"
# SQLITE_DB_PATH="./data/local.sqlite"

Generate 32-character random string:

# Using openssl
openssl rand -hex 32

# Using Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Start the Application

# Start Next.js application
pnpm run dev:next

# Or start Nuxt.js application
pnpm run dev:nuxt

# Or start TanStack Start application
pnpm run dev:tanstack

# Visit http://localhost:7001

Congratulations! You have successfully run the TinyShip application.

Next Steps

  • Database Configuration - multi-dialect guide (PostgreSQL / SQLite / D1)
Basic Configuration

App name, Logo, theme, internationalization

Authentication Configuration

More login methods (Google, GitHub, WeChat, SMS)

Payment Configuration

Integrate Stripe, WeChat Pay, Creem

Deployment

Deploy to Vercel, Docker, VPS

TinyShip User Guide

A modern, feature-complete monorepo starter kit designed for building SaaS applications

Basic Configuration

Application name, Logo, theme system and internationalization configuration

On this page

System RequirementsQuick InstallationClone the ProjectInstall AI Agent Skills (Optional, Recommended)Install PNPM (if not installed)Copy Environment Variables TemplateInstall Project DependenciesDatabase Configuration1. PostgreSQL (default, recommended, most stable)Method 1: Using Docker (Recommended)Method 2: Local InstallationMethod 3: Cloud Database Service2. SQLite (optional, D1-compatible)3. D1 and SQLite relationshipMinimal Auth ConfigurationStart the ApplicationNext Steps