klinsmaya/tinyship-skills
1
0
Fork 0
mirror of https://gh-proxy.org/https://github.com/klinsmaya/tinyship-skills.git synced 2026-11-08 01:06:53 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat: add template detection and route skills for shipeasy vs tinyship-cf

Browse Source 
- add shared references/template-detection.md (detection + cheat sheet)
- tinyship-cloudflare: Step 0 routing — tinyship-cf projects take a fast
  path (secrets + D1 migrations + deploy), shipeasy keeps the full wizard
  with a recommendation to prefer tinyship-cf for new CF projects
- tinyship-setup: Step 0 template detection, branch env file, database,
  framework selection, pricing mode, and cleanup steps per template
- AGENTS.md: document shared references directory
This commit is contained in:
Viking Zhang
2026-08-24 15:07:55 +08:00
parent fde5860cc3
commit f859a6c090
4 changed files with 217 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+6
View File
@@ -21,3 +21,9 @@ Each skill follows the [Agent Skills specification](https://agentskills.io):
- `SKILL.md` with YAML frontmatter (`name` + `description`)
- Optional `references/` subdirectory for progressive disclosure
- Content stays under 500 lines per SKILL.md
## Shared References
- `references/template-detection.md` — detect shipeasy vs tinyship-cf and the
difference cheat sheet. Setup/configuration skills should read it first and
follow the branch for the detected template.
references/template-detection.md
+42
View File
@@ -0,0 +1,42 @@
# Template Detection — shipeasy vs tinyship-cf
TinyShip has two template repositories. Before running any setup/configuration
steps, detect which one the current project is, and follow the matching column
in the cheat sheet below.
## How to Detect
Check the project root:
| Condition | Template |
|-----------|----------|
| `apps/next-app` or `apps/nuxt-app` exists | **shipeasy** (multi-framework) |
| No `apps/next-app`, and `apps/tanstack-app/wrangler.jsonc` exists | **tinyship-cf** (Cloudflare-only) |
```bash
ls apps/ # shipeasy: next-app nuxt-app tanstack-app
# tinyship-cf: tanstack-app only
ls apps/tanstack-app/wrangler.jsonc
```
## Difference Cheat Sheet
| Item | shipeasy | tinyship-cf |
|------|----------|-------------|
| Env file (local) | Root `.env` (copied from `env.example`) | `apps/tanstack-app/.dev.vars` (copied from `.dev.vars.example`) |
| Non-secret config | `.env` | `wrangler.jsonc` `vars` + `.dev.vars` |
| Frameworks | Next.js / Nuxt.js / TanStack Start (choose one) | TanStack Start only |
| Dev command | `pnpm dev:next` / `dev:nuxt` / `dev:tanstack` | `pnpm dev` (port 7001) |
| Build command | `pnpm build:next` / etc. | `pnpm build` |
| Default database | SQLite (local) or PostgreSQL | Cloudflare D1 (local + remote) |
| DB setup command | `pnpm db:push` / `db:push:sqlite` + `db:seed*` | `npx wrangler d1 migrations apply tinyship-db --local` |
| Deployment | Docker / Vercel / VPS / Cloudflare Workers | Cloudflare Workers only (`pnpm deploy:cf`) |
| AI architecture | Direct provider SDKs (`@ai-sdk/*`), keys in `.env` | AI Gateway + Workers AI binding; third-party keys in Gateway dashboard (BYOK) |
| Runtime | Node.js | Cloudflare Workers (workerd) |
## Rules of Thumb
- When writing env vars: `.env` for shipeasy, `.dev.vars` for tinyship-cf — never mix.
- tinyship-cf has **no framework selection or framework cleanup steps** — skip them.
- For Cloudflare deployment, tinyship-cf is the recommended template; shipeasy's
Cloudflare support is legacy.
skills/tinyship-cloudflare/SKILL.md
+127 -23
View File
@@ -15,21 +15,124 @@ One-stop wizard to configure the full Cloudflare stack for TinyShip (TanStack St
decision point and wait for their answer before proceeding. NEVER make choices
on the user's behalf.**
> **Scope:** This skill configures TanStack Start (`apps/tanstack-app`) for Cloudflare
## Step 0: Detect Template & Route
First, read [../../references/template-detection.md](../../references/template-detection.md)
and detect which template the current project is.
### If the project is tinyship-cf (Cloudflare-only template)
The project is already Cloudflare-native — bindings, D1, and the Workers setup are
preconfigured. Do NOT run framework cleanup or wrangler scaffolding. Go directly to
the **Fast Path** below.
### If the project is shipeasy (multi-framework)
**⛔ STOP — You MUST tell the user and ask before proceeding.**
> TinyShip now has a dedicated Cloudflare template (**tinyship-cf**) that ships
> preconfigured for Workers (no hacks, no framework cleanup needed). For NEW
> Cloudflare projects, starting from tinyship-cf is recommended.
>
> - **Continue here** — configure Cloudflare in this shipeasy project (makes sense
> if you already built features on it)
> - **Switch to tinyship-cf** — start fresh from the dedicated template and migrate
> your changes manually
If the user chooses to continue, follow the **Full Wizard** below.
---
## Fast Path (tinyship-cf projects)
### 1. Wrangler Login
```bash
cd apps/tanstack-app
npx wrangler login
npx wrangler whoami # capture the Account ID
```
If already logged in, skip and tell the user.
### 2. Local env
```bash
cp apps/tanstack-app/.dev.vars.example apps/tanstack-app/.dev.vars
```
Set `BETTER_AUTH_SECRET` (`openssl rand -hex 32`). Verify local dev:
```bash
pnpm dev # http://localhost:7001
```
### 3. Remote database
The D1 database is already bound in `wrangler.jsonc`. Apply migrations and verify:
```bash
npx wrangler d1 migrations apply tinyship-db --remote
```
For Hyperdrive + PostgreSQL instead of D1, read and follow
[references/hyperdrive-setup.md](references/hyperdrive-setup.md).
### 4. Secrets
**⛔ STOP — ask the user which features they use, then set only those secrets.**
```bash
npx wrangler secret put BETTER_AUTH_SECRET # required
# Payments (as needed): STRIPE_SECRET_KEY, PAYPAL_CLIENT_ID/SECRET,
# DODO_PAYMENTS_API_KEY/WEBHOOK_KEY, CREEM_API_KEY/WEBHOOK_SECRET
# AI image/video (as needed): QWEN_API_KEY, FAL_API_KEY,
# GOOGLE_GENERATIVE_AI_API_KEY, VOLCENGINE_ACCESS_KEY_ID
# Email: RESEND_API_KEY
```
Notes:
- **Chat AI needs no secret** — it runs on Workers AI + AI Gateway. Third-party
chat keys (OpenAI/DeepSeek) are managed in the AI Gateway dashboard (BYOK).
- `AI_GATEWAY_ID` defaults to `default`; if the user's gateway has a different
name, set it in `wrangler.jsonc` `vars`.
- Payment webhook URLs in each provider dashboard must point to the production domain.
### 5. Optional extras
Ask about each, then read and follow the matching reference:
- **R2 storage** — [references/r2-setup.md](references/r2-setup.md) (bucket already bound)
- **Email Sending** — [references/email-setup.md](references/email-setup.md)
- **Turnstile** — [references/turnstile-setup.md](references/turnstile-setup.md)
### 6. Deploy
```bash
pnpm deploy:cf
```
Verify: home page 200, `/en/pricing` 200, login works. If `pricing_plan` table is
empty and `PRICING_MODE=dynamic`, log in as admin → Admin → Pricing Plans →
**Import Static** to populate plans.
Go to **Step 8: Summary**.
---
## Full Wizard (shipeasy projects)
> **Scope:** This wizard configures TanStack Start (`apps/tanstack-app`) for Cloudflare
> Workers deployment. Next.js and Nuxt.js are designed for Node.js environments and
> do not deploy to Workers. If the user hasn't chosen TanStack Start yet, suggest
> running the `tinyship-setup` skill first.
> do not deploy to Workers.
## Prerequisites
Before starting, verify:
### Prerequisites
1. **Node.js >= 22.20.0** — run `node -v`
2. **pnpm >= 9.0.0** — run `pnpm -v`
3. **Dependencies installed** — if `node_modules/` is missing, run `pnpm install`
4. **A Cloudflare account** — https://dash.cloudflare.com/sign-up
## Step 1: Wrangler Login
### Step 1: Wrangler Login
Run the following to authenticate with Cloudflare:
@@ -49,7 +152,7 @@ Capture the **Account ID** from the output — it will be reused for R2 and Emai
If the user is already logged in (`wrangler whoami` shows account info), skip this step
and tell the user.
## Step 2: Framework Cleanup
### Step 2: Framework Cleanup
**⛔ STOP — You MUST ask the user before proceeding.**
@@ -64,7 +167,7 @@ Do you want to remove the Next.js and Nuxt.js apps from the project?**
| **Yes — clean up** | Remove `apps/next-app` and `apps/nuxt-app`, update workspace config |
| **No — keep them** | Leave them in place (useful if you also plan Node.js deployments) |
### If the user chooses Yes:
#### If the user chooses Yes:
Follow the cleanup procedure from the `tinyship-setup` skill:
read and follow [../tinyship-setup/references/framework-cleanup.md](../tinyship-setup/references/framework-cleanup.md)
@@ -81,11 +184,11 @@ Summary of what to do:
After cleanup, run `pnpm typecheck` and `pnpm build` (which now point to TanStack) to verify.
### If the user chooses No:
#### If the user chooses No:
Skip this step. The other apps remain in the project but won't be deployed to Workers.
## Step 3: Database — D1 or Hyperdrive
### Step 3: Database — D1 or Hyperdrive
**⛔ STOP — You MUST ask the user before proceeding.**
@@ -100,11 +203,11 @@ Explain the trade-offs:
- **D1**: Fully managed, included in Workers billing, 5-10 GB limit, single-writer constraint
- **Hyperdrive**: Needs an external PostgreSQL, but no storage limits, same DB across all 3 apps
### If the user chooses D1:
#### If the user chooses D1:
Read and follow [references/d1-setup.md](references/d1-setup.md).
### If the user chooses Hyperdrive:
#### If the user chooses Hyperdrive:
Read and follow [references/hyperdrive-setup.md](references/hyperdrive-setup.md).
@@ -117,7 +220,7 @@ pnpm dev:cf
Check that the app loads and database-dependent pages work. Tell the user the results.
## Step 4: R2 Storage (Optional)
### Step 4: R2 Storage (Optional)
**⛔ STOP — You MUST ask the user before proceeding.**
@@ -126,7 +229,7 @@ Ask: **Do you want to set up Cloudflare R2 for file storage (images, uploads)?**
- **Yes** — read and follow [references/r2-setup.md](references/r2-setup.md)
- **No** — skip (can be configured later)
## Step 5: Email Sending (Optional)
### Step 5: Email Sending (Optional)
**⛔ STOP — You MUST ask the user before proceeding.**
@@ -136,7 +239,7 @@ Ask: **Do you want to use Cloudflare Email Sending for transactional emails
- **Yes** — read and follow [references/email-setup.md](references/email-setup.md)
- **No** — skip (default is Resend, or configure later)
## Step 6: Turnstile Bot Protection (Optional)
### Step 6: Turnstile Bot Protection (Optional)
**⛔ STOP — You MUST ask the user before proceeding.**
@@ -145,7 +248,7 @@ Ask: **Do you want to enable Cloudflare Turnstile (CAPTCHA) for login/signup pro
- **Yes** — read and follow [references/turnstile-setup.md](references/turnstile-setup.md)
- **No** — skip (disabled by default, safe to add later)
## Step 7: Deploy to Workers
### Step 7: Deploy to Workers
**⛔ STOP — You MUST ask the user before proceeding.**
@@ -154,13 +257,14 @@ Ask: **Do you want to deploy to Cloudflare Workers now, or just finish the local
- **Deploy now** — read and follow [references/workers-deploy.md](references/workers-deploy.md)
- **Later** — tell the user they can deploy anytime with `cd apps/tanstack-app && pnpm run deploy:cf`
## Step 8: Summary
### Step 8: Summary
After setup is complete, provide a summary of what was configured:
```
✅ Cloudflare Setup Complete
─────────────────────────────
Template: [tinyship-cf (fast path) / shipeasy (full wizard)]
Frameworks: TanStack Start only [Next/Nuxt removed / kept]
Workers: TanStack Start on Cloudflare Workers
Database: [D1 / Hyperdrive+PG] — configured and verified
@@ -170,21 +274,21 @@ Turnstile: [enabled / skipped]
Deployment: [deployed to <url> / ready for deploy]
Next steps:
- Run `cd apps/tanstack-app && pnpm dev:cf` for local CF dev
- Run `cd apps/tanstack-app && pnpm run deploy:cf` to deploy
- tinyship-cf: `pnpm dev` for local dev, `pnpm deploy:cf` to deploy
- shipeasy: `cd apps/tanstack-app && pnpm dev:cf` / `pnpm run deploy:cf`
- Use `npx wrangler tail` to view live logs
```
## Reference Files in TinyShip Repo
When executing this skill, read these files from the user's TinyShip project for context:
When executing this skill, read these files from the user's project for context:
- `apps/tanstack-app/wrangler.jsonc` — current Wrangler config
- `apps/tanstack-app/CF-NOTES.md` — known Cloudflare pitfalls
- `apps/tanstack-app/.dev.vars.example` — local dev vars template
- `apps/tanstack-app/.dev.vars.example` — local dev vars template (tinyship-cf)
- `env.example` — all environment variables (shipeasy only)
- `apps/tanstack-app/vite.config.ts` — CF plugin conditional loading
- `docs/user-guide/deployment/cloudflare-workers.md` — full deployment guide
- `config/storage.ts` — R2 config structure
- `config/email.ts` — Email config structure
- `config/captcha.ts` — Turnstile config structure
- `env.example` — all environment variables
skills/tinyship-setup/SKILL.md
+42 -10
View File
@@ -15,6 +15,13 @@ Interactive setup wizard for TinyShip SaaS starter projects.
decision point and wait for their answer before proceeding. NEVER make choices
on the user's behalf.**
## Step 0: Detect Template
Read [../../references/template-detection.md](../../references/template-detection.md)
and detect which template the current project is (**shipeasy** or **tinyship-cf**).
Follow the matching branch in each step below. For tinyship-cf, steps marked
"shipeasy only" are skipped entirely.
## Prerequisites
Before starting, verify:
@@ -26,17 +33,34 @@ If prerequisites fail, tell the user what to install and STOP.
## Step 1: Environment Configuration
**shipeasy:**
1. Copy the template: `cp env.example .env`
2. Generate an auth secret: `openssl rand -hex 32`
3. Set the generated secret in `.env` as `BETTER_AUTH_SECRET`
**tinyship-cf:**
1. Copy the template: `cp apps/tanstack-app/.dev.vars.example apps/tanstack-app/.dev.vars`
2. Generate an auth secret: `openssl rand -hex 32`
3. Set the generated secret in `.dev.vars` as `BETTER_AUTH_SECRET`
Do NOT configure the database dialect yet — that depends on the user's choice in Step 2.
## Step 2: Choose Database
**⛔ STOP — You MUST ask the user before proceeding.**
Present these options and wait for the user's response:
**tinyship-cf:** the default (and recommended) database is **Cloudflare D1** — it is
already bound in `wrangler.jsonc` and needs no connection string. Simply run:
```bash
cd apps/tanstack-app
npx wrangler d1 migrations apply tinyship-db --local
```
Then skip to Step 3. If the user specifically wants PostgreSQL (Hyperdrive), hand off
to the `tinyship-cloudflare` skill's Hyperdrive path.
**shipeasy:** present these options and wait for the user's response:
| Option | Database | Best For |
|--------|----------|----------|
@@ -128,7 +152,7 @@ pnpm db:seed
- **Admin**: `admin@example.com` / `admin123` (role: admin)
- **User**: `user@example.com` / `user123456` (role: user)
## Step 3: Choose Framework
## Step 3: Choose Framework (shipeasy only)
**⛔ STOP — You MUST ask the user before proceeding.**
@@ -140,9 +164,15 @@ Present these options and wait for the user's response:
| **B** | **Nuxt.js** | Vue developers, convention-over-configuration | `pnpm dev:nuxt` |
| **C** | **TanStack Start** | Lightweight React, Cloudflare Workers edge deployment | `pnpm dev:tanstack` |
After the user chooses, start the selected framework and verify:
> **Note:** For a Cloudflare Workers deployment, recommend starting from the
> **tinyship-cf** template instead — it is preconfigured for Workers with no hacks.
1. Run the dev command (e.g., `pnpm dev:next`)
**tinyship-cf:** skip selection — TanStack Start is the only framework. Dev command
is `pnpm dev`.
After the user chooses (or for tinyship-cf), start the app and verify:
1. Run the dev command (e.g., `pnpm dev:next` / `pnpm dev`)
2. Open `http://localhost:7001` — home page should load
3. Check `http://localhost:7001/api/health` — should return a response
4. Try logging in with `admin@example.com` / `admin123`
@@ -167,7 +197,7 @@ shown directly on the pricing page. This is the default behavior.
### If the user chooses Dynamic:
Set in `.env`:
Set in `.env` (shipeasy) or `apps/tanstack-app/.dev.vars` (tinyship-cf):
```
PRICING_MODE="dynamic"
```
@@ -183,13 +213,14 @@ for creating, editing, and managing plans without code changes. Features include
- Import existing static plans into the database with one click
> **Note:** The database migration for `pricing_plan` table is already included.
> The seed data creates 5 example plans covering different providers and currencies.
> You can manage all plans via the admin panel at `/admin/pricing` after setup.
> For tinyship-cf, `PRICING_MODE` also needs to be set in `wrangler.jsonc` `vars`
> for the deployed Worker.
Tell the user: "You can always switch between modes later by changing `PRICING_MODE`
in your `.env` file. Static plans in `config/payment.ts` remain available as a fallback."
in your env file. Static plans in `config/payment.ts` remain available as a fallback."
## Step 5: Framework Cleanup (Optional)
## Step 5: Framework Cleanup (Optional, shipeasy only)
**⛔ STOP — You MUST ask the user before proceeding. Do NOT delete anything without explicit confirmation.**
@@ -220,13 +251,14 @@ After setup is complete, tell the user what they can do next:
2. **Add authentication** — configure OAuth providers (use `tinyship-auth` skill)
3. **Set up payments** — integrate payment providers (use `tinyship-payment` skill)
4. **Configure AI** — set up AI chat/image/video features (use `tinyship-ai` skill)
5. **Deploy** — deploy to Vercel, Docker, or Cloudflare (use `tinyship-deploy` skill)
5. **Deploy** — deploy to Vercel, Docker, or Cloudflare (use `tinyship-deploy` skill;
for Cloudflare Workers, use `tinyship-cloudflare` for the all-in setup)
## Reference Files in TinyShip Repo
When executing this skill, read these files from the user's TinyShip project for context:
- `env.example` — full list of environment variables with descriptions
- `env.example` (shipeasy) / `apps/tanstack-app/.dev.vars.example` (tinyship-cf) — environment variables
- `docs/user-guide/get-started.md` — detailed getting started guide
- `docs/user-guide/database.md` — database configuration details
- `docs/user-guide/payment/dynamic-pricing.md` — dynamic pricing feature guide